Overview
Flow ID: onboarding-model-upload
Category: Onboarding & Initial Setup
Estimated Duration: 5-15 minutes (plus upload time)
User Role: All Users (first time)
Complexity: Moderate
Purpose: During the onboarding wizard, users are guided to upload their first AI language model, which is essential for using chat features. This embedded upload experience is simplified and explained within the setup flow.
Related Flows
- First-Time Application Setup - Parent onboarding flow
- Upload Large Language Model - Standalone upload (similar process)
- Select Chat Style During Onboarding - Next step typically
Prerequisites
Before starting, users must have:
- Onboarding wizard active
- AI model file available on computer
- Sufficient disk space for model
- Understanding that model is required for chat
Step-by-Step Flow
Main Path (Happy Path)
Step 1: Model Upload Step Appears
- User Action: Arrive at model upload step in onboarding
- System Response: Model upload interface displays
- UI Elements Visible:
- Step header: "Upload Your AI Model" or "Step 1: Add Language Model"
- Progress indicator: "Step 1 of 4" or similar
- Explanation text: "You need an AI language model to chat. Upload your model file to get started."
- File upload area (dropzone or button)
- "Choose File" button
- "I don't have a model yet" help link or text
- "Skip this step" button (less prominent)
- "Next" button (likely disabled until upload completes)
- Visual Cues:
- Clear step identification
- Explanatory text in friendly tone
- Upload area prominent
Step 2: Read Explanation
- User Action: Read why model is needed and what to upload
- System Response: Information helps user understand requirement
- UI Elements Visible:
- Explanation text about models
- Supported file formats listed
- May include link to documentation or help
Step 3: Select Model File
- User Action: Click "Choose File" button
- System Response: File browser opens
- UI Elements Visible:
- Operating system file browser
- File type filter (may show .gguf and other supported formats)
Step 4: Navigate to Model File
- User Action: Browse to model file location, select file, click "Open"
- System Response:
- File browser closes
- Filename appears in upload area
- Model name auto-populates
- Upload begins automatically or "Upload" button appears
- UI Elements Visible:
- Selected filename displayed
- Model name field (auto-filled, editable)
- Model type: "Large Language Model" (auto-set)
- Progress bar (if upload started)
- OR "Upload" button to initiate
Step 5: Upload Progress
- User Action: Wait for upload (5-30 minutes depending on model size)
- System Response:
- Progress bar advances
- Percentage updates
- Upload status displayed
- UI Elements Visible:
- Progress bar (0-100%)
- Percentage: "35%" or similar
- Upload speed (possibly)
- Estimated time remaining (possibly)
- Model size and upload progress (e.g., "2.5 GB of 7.2 GB")
- Visual Cues:
- Animated progress bar
- Numbers increasing
- May show file size uploaded
Step 6: Upload Completes
- User Action: No action required
- System Response:
- Progress reaches 100%
- Success message appears
- Checkmark or success icon shown
- "Next" button becomes enabled
- UI Elements Visible:
- Success message: "Model uploaded successfully!"
- Green checkmark icon
- Model name confirmed
- "Next" button now clickable (blue/active)
- Visual Cues:
- Green success color
- Checkmark animation
- Enabled next button
Step 7: Proceed to Next Step
- User Action: Click "Next" button
- System Response:
- Onboarding advances to next step
- Model upload step marked complete
- UI Elements Visible:
- Next onboarding step loads
- Progress indicator updates: "Step 2 of 4"
- Visual Cues: Smooth step transition
Final Step: Model Uploaded via Onboarding
- Success Indicator:
- Model uploaded and registered
- Can proceed with onboarding
- Model will be available after onboarding completes
- System State Change:
- Model file stored in application
- Model registered in database
- Model will load when onboarding completes
- Ready for use in conversations
- Next Possible Actions:
- Continue to next onboarding step
- Complete remaining onboarding
- Use model after onboarding finishes
Alternative Paths & Strategies
Strategy A: Skip Model Upload
When to use: Don't have model file yet or want to upload later
Steps:
- On model upload step, click "Skip this step"
- Warning may appear: "You need a model to chat"
- Confirm skip
- Proceed to next step
- Must upload model manually later to use chat
Strategy B: Get Model First
When to use: Realize you need model file but don't have it
Steps:
- See model upload step
- Click "I don't have a model yet" help link
- Instructions appear for obtaining models
- Exit application or pause onboarding
- Obtain model file
- Return to onboarding and upload
Strategy C: Upload Model, Skip Other Steps
When to use: Only want to complete essential configuration
Steps:
- Complete model upload step
- Skip all subsequent steps
- Exit onboarding with model configured
- Minimum viable setup complete
Error States & Recovery
Error 1: Wrong File Type Selected
Cause: User selects non-model file
User Experience:
- Error: "Invalid file type" or "Not a model file"
- Upload doesn't proceed or fails
Recovery Steps:
- Read error message
- Click "Choose File" again
- Select correct model file (typically .gguf or similar)
- Verify file is actually an AI model
- Try again with correct file
Error 2: Upload Interrupted
Cause: Closed application, lost connection, or error during upload
User Experience:
- Upload progress stops
- Error message may appear
- Model not available
Recovery Steps:
- Restart onboarding or application
- May resume at model upload step
- Select file and upload again
- Ensure stable conditions (don't close app during upload)
Error 3: Insufficient Disk Space
Cause: Not enough free space for large model
User Experience:
- Error during upload: "Insufficient disk space"
- Upload fails partway
Recovery Steps:
- Free up disk space (delete unnecessary files)
- Consider uploading smaller model
- Try again after freeing space
- Or skip and upload later when space available
Error 4: Model File Corrupted
Cause: Model file is damaged
User Experience:
- Upload completes but validation fails
- Error: "Invalid model file" or "Corrupted file"
Recovery Steps:
- Re-download model file from source
- Verify file integrity (check file size, hash if available)
- Upload fresh copy
- If issue persists, try different model
Version History
| Date | Version | Author | Changes |
|---|---|---|---|
| 2025-10-04 | 1.1 | Iternal Technologies | Initial comprehensive documentation |
Notes
Important Considerations:
- Model upload is typically the first and most important onboarding step
- Cannot use chat features without a model
- Large models (10+ GB) will take significant time to upload
- Application must remain open during upload
- Upload progress is part of onboarding progress
- Completing upload doesn't automatically select model (may need to select in settings)
Recommended First Models:
- Medium-sized models (7-8B parameters): Good balance for most hardware
- Smaller models (3B parameters): Faster, lower resource usage
- Larger models (13B+ parameters): Better quality but require more powerful hardware
Best Practices:
- Have model file ready before starting onboarding
- Ensure stable environment for upload (plugged in, not on battery)
- Don't close application during upload
- Verify upload completes successfully before proceeding
- Test model with simple chat after onboarding
Common User Questions:
- "Where do I get a model file?" - External sources; application doesn't provide downloads
- "What model should I upload first?" - Medium-sized (7-8B) recommended for most users
- "Can I skip and upload later?" - Yes, but can't use chat until model uploaded
- "How long will upload take?" - Depends on file size; 5-30 minutes typical
- "Can I upload more models later?" - Yes, through Settings page
Trigger
What initiates this flow:
- User manually initiates
- System event (reaches model upload step in onboarding wizard)
Specific trigger: User proceeds through onboarding wizard and reaches the model upload step (typically Step 1).
User Intent Analysis
Primary Intent
Upload first AI model as part of initial setup to enable core chat functionality.
Secondary Intents
- Understand why model is needed
- Successfully complete essential onboarding step
- Prepare application for immediate use
Subintents
- Follow guided process correctly
- Verify model uploads successfully
- Understand model's role in application