|
| 1 | +# Onboarding Video System |
| 2 | + |
| 3 | +This module implements a video-based onboarding system for applicants with sequential video watching validation. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **Sequential Video Watching**: Users must complete videos in order (1 → 2 → 3 → 4) |
| 8 | +- **Progress Tracking**: Real-time tracking of video watch progress |
| 9 | +- **Validation**: Users must watch at least 90% of each video to unlock the next one |
| 10 | +- **Visual Progress**: Stepper UI showing completion status |
| 11 | +- **Database Persistence**: All progress is saved to the database |
| 12 | + |
| 13 | +## Database Setup |
| 14 | + |
| 15 | +1. Run the SQL migration file to create the required table: |
| 16 | + |
| 17 | +```bash |
| 18 | +# Apply the migration in Supabase |
| 19 | +psql -h your-supabase-host -U postgres -d postgres -f apps/codebility/supabase/migrations/create_onboarding_videos_table.sql |
| 20 | +``` |
| 21 | + |
| 22 | +Or use Supabase Dashboard: |
| 23 | +- Go to SQL Editor in your Supabase dashboard |
| 24 | +- Copy the contents of `supabase/migrations/create_onboarding_videos_table.sql` |
| 25 | +- Run the SQL query |
| 26 | + |
| 27 | +## Video Setup |
| 28 | + |
| 29 | +### Option 1: Supabase Storage (Recommended) |
| 30 | + |
| 31 | +1. Create a storage bucket named `onboarding-videos` in Supabase |
| 32 | +2. Upload your 4 videos with the following naming convention: |
| 33 | + - `onboarding-1.mp4` - Introduction |
| 34 | + - `onboarding-2.mp4` - Company Culture |
| 35 | + - `onboarding-3.mp4` - Tools & Processes |
| 36 | + - `onboarding-4.mp4` - Getting Started |
| 37 | + |
| 38 | +3. Update the `VIDEO_URLS` in `_components/OnboardingClient.tsx`: |
| 39 | +```typescript |
| 40 | +const VIDEO_URLS = { |
| 41 | + 1: "https://your-project.supabase.co/storage/v1/object/public/onboarding-videos/onboarding-1.mp4", |
| 42 | + 2: "https://your-project.supabase.co/storage/v1/object/public/onboarding-videos/onboarding-2.mp4", |
| 43 | + 3: "https://your-project.supabase.co/storage/v1/object/public/onboarding-videos/onboarding-3.mp4", |
| 44 | + 4: "https://your-project.supabase.co/storage/v1/object/public/onboarding-videos/onboarding-4.mp4", |
| 45 | +}; |
| 46 | +``` |
| 47 | + |
| 48 | +### Option 2: Public Folder |
| 49 | + |
| 50 | +1. Create a `public/videos` folder in the root of your Next.js app |
| 51 | +2. Add your 4 videos with the naming convention above |
| 52 | +3. The current URLs in `OnboardingClient.tsx` are already configured for this option |
| 53 | + |
| 54 | +### Option 3: External Video Hosting |
| 55 | + |
| 56 | +Use any video hosting service (Vimeo, YouTube, AWS S3, etc.) and update the URLs accordingly. |
| 57 | + |
| 58 | +## Flow |
| 59 | + |
| 60 | +1. **Applicant Step 3** (`/applicant/waiting`): |
| 61 | + - When user status is "onboarding" and they've joined Discord |
| 62 | + - "Start Onboarding" button appears |
| 63 | + - Clicking routes to `/applicant/onboarding` |
| 64 | + |
| 65 | +2. **Video Watching** (`/applicant/onboarding` - Step 1-4): |
| 66 | + - Shows progress stepper with 5 steps |
| 67 | + - Displays current video with player controls |
| 68 | + - Tracks watch progress (must watch 90%+ to complete) |
| 69 | + - Next video unlocks only after completing previous one |
| 70 | + - "Proceed to Quiz" button appears after all 4 videos |
| 71 | + |
| 72 | +3. **Quiz** (Step 5a): |
| 73 | + - 6 multiple-choice questions about the onboarding content |
| 74 | + - Must score 70% or higher to pass |
| 75 | + - Shows detailed results with correct answers |
| 76 | + - Can retake if failed |
| 77 | + - Proceeds to commitment after passing |
| 78 | + |
| 79 | +4. **Commitment Agreement** (Step 5b): |
| 80 | + - **Bold warning** to take time thinking through the decision |
| 81 | + - Details the 3-6 months minimum commitment requirement |
| 82 | + - Two acknowledgment checkboxes required |
| 83 | + - Digital signature box (mouse/touch drawing) |
| 84 | + - "I'm Ready to Join Codebility" button |
| 85 | + |
| 86 | +5. **Completion**: |
| 87 | + - Quiz score and signature saved to database |
| 88 | + - User status changes from "onboarding" to "waitlist" |
| 89 | + - Redirects back to waiting page |
| 90 | + |
| 91 | +## Database Schema |
| 92 | + |
| 93 | +### onboarding_videos table |
| 94 | +```sql |
| 95 | +onboarding_videos |
| 96 | +├── id (uuid, PK) |
| 97 | +├── applicant_id (uuid, FK → applicant.id) |
| 98 | +├── video_number (integer, 1-4) |
| 99 | +├── completed (boolean) |
| 100 | +├── watched_duration (numeric) |
| 101 | +├── total_duration (numeric) |
| 102 | +├── completed_at (timestamptz) |
| 103 | +├── created_at (timestamptz) |
| 104 | +└── updated_at (timestamptz) |
| 105 | +``` |
| 106 | + |
| 107 | +### applicant table (new fields) |
| 108 | +```sql |
| 109 | +applicant (additions) |
| 110 | +├── quiz_score (integer) - Score achieved on quiz |
| 111 | +├── quiz_total (integer) - Total possible points |
| 112 | +├── signature_data (text) - Base64 encoded signature image |
| 113 | +└── commitment_signed_at (timestamptz) - When agreement was signed |
| 114 | +``` |
| 115 | + |
| 116 | +## Components |
| 117 | + |
| 118 | +### `OnboardingClient.tsx` |
| 119 | +Main client component that manages the complete onboarding flow: |
| 120 | +- Video watching phase with navigation |
| 121 | +- Quiz phase after all videos complete |
| 122 | +- Commitment phase after passing quiz |
| 123 | +- State management between all phases |
| 124 | + |
| 125 | +### `VideoPlayer.tsx` |
| 126 | +Video player component with: |
| 127 | +- HTML5 video controls |
| 128 | +- Progress tracking |
| 129 | +- Watch validation (90% threshold) |
| 130 | +- Locked state for sequential videos |
| 131 | +- Auto-save progress to database |
| 132 | + |
| 133 | +### `Quiz.tsx` |
| 134 | +Quiz component featuring: |
| 135 | +- 6 multiple-choice questions |
| 136 | +- Progress indicator |
| 137 | +- 70% passing grade requirement |
| 138 | +- Detailed answer review with explanations |
| 139 | +- Retake functionality for failed attempts |
| 140 | + |
| 141 | +### `Commitment.tsx` |
| 142 | +Commitment agreement component with: |
| 143 | +- Prominent warning message about taking time to decide |
| 144 | +- Detailed commitment requirements (3-6 months minimum) |
| 145 | +- Two acknowledgment checkboxes |
| 146 | +- Canvas-based digital signature (mouse/touch support) |
| 147 | +- "I'm Ready to Join" final confirmation button |
| 148 | + |
| 149 | +### `OnboardingStepper.tsx` |
| 150 | +Visual stepper showing: |
| 151 | +- 5 steps with titles (4 videos + Quiz & Commitment) |
| 152 | +- Completion status (checkmarks) |
| 153 | +- Current step indicator |
| 154 | +- Progress line between steps |
| 155 | + |
| 156 | +## Server Actions |
| 157 | + |
| 158 | +### `getOnboardingProgress(applicantId)` |
| 159 | +Fetches all video progress for an applicant and calculates current video. |
| 160 | + |
| 161 | +### `updateVideoProgress({ applicantId, videoNumber, watchedDuration, totalDuration, completed })` |
| 162 | +Updates or creates video progress record in database. |
| 163 | + |
| 164 | +### `saveQuizAndCommitment({ applicantId, quizScore, quizTotal, signature })` |
| 165 | +Saves quiz results and signature data to the applicant record. |
| 166 | + |
| 167 | +### `completeOnboarding(codevId, newStatus)` |
| 168 | +Updates user status after onboarding completion. Default status is "waitlist". |
| 169 | + |
| 170 | +## Customization |
| 171 | + |
| 172 | +### Video Titles and Descriptions |
| 173 | +Edit in `OnboardingClient.tsx`: |
| 174 | +```typescript |
| 175 | +const VIDEO_TITLES = { |
| 176 | + 1: "Your Title Here", |
| 177 | + // ... |
| 178 | +}; |
| 179 | + |
| 180 | +const VIDEO_DESCRIPTIONS = { |
| 181 | + 1: "Your description here", |
| 182 | + // ... |
| 183 | +}; |
| 184 | +``` |
| 185 | + |
| 186 | +### Watch Threshold |
| 187 | +Change the completion percentage in `VideoPlayer.tsx`: |
| 188 | +```typescript |
| 189 | +// Current: 90% threshold |
| 190 | +if (percentWatched >= 90 && !hasWatched) { |
| 191 | + // Change 90 to your desired percentage |
| 192 | +} |
| 193 | +``` |
| 194 | + |
| 195 | +### Styling |
| 196 | +All components use Tailwind CSS and can be customized by modifying the className properties. |
| 197 | + |
| 198 | +## Security Features |
| 199 | + |
| 200 | +- Row Level Security (RLS) policies ensure users can only access their own progress |
| 201 | +- Video right-click disabled to prevent easy downloading |
| 202 | +- Download controls disabled |
| 203 | +- Progress validation on server-side |
| 204 | + |
| 205 | +## Troubleshooting |
| 206 | + |
| 207 | +### Videos not loading |
| 208 | +- Check video URLs in `VIDEO_URLS` |
| 209 | +- Ensure videos are in correct format (MP4 recommended) |
| 210 | +- Check browser console for network errors |
| 211 | +- Verify Supabase storage bucket permissions (if using Supabase) |
| 212 | + |
| 213 | +### Progress not saving |
| 214 | +- Check database connection |
| 215 | +- Verify `onboarding_videos` table exists |
| 216 | +- Check browser console for errors |
| 217 | +- Ensure applicant_id is valid |
| 218 | + |
| 219 | +### User can't access onboarding page |
| 220 | +- Verify user's `application_status` is "onboarding" |
| 221 | +- Check if user has joined Discord (checkbox must be checked) |
| 222 | +- Verify applicant record exists in database |
0 commit comments