Progress Tracking

​

Overview

​

How Progress Works

​

Progress States

1. Not Started - Default state for all classes
2. In Progress - Video has been played but not completed
3. Complete - Class has been marked as finished

​

Class Keys

const classKey = `${catIdx}|${routeIdx}|${courseIdx}|${modIdx}|${classIdx}`
// Example: "0|1|2|3|4" for specific class

​

Automatic Progress Tracking

​

Video Playback Tracking

{
  status: 'in_progress',
  lastWatched: '2024-03-15T14:30:00.000Z',
  watchTime: 125.5  // seconds
}

• Video play event fires
• Current playback time is recorded
• Timestamp is saved

​

Auto-Complete on Finish

• Video plays to the end (ended event)
• Progress is saved with completion timestamp
• Next class auto-advances after 1.5 seconds

{
  status: 'complete',
  completedAt: '2024-03-15T14:45:32.000Z'
}

​

Manual Progress Management

​

Mark Complete Button

1. Open any class in the player
2. Click Completada button below the video
3. Button updates to show checkmark: ✅ Completada
4. Sidebar updates to reflect completion

• Mark non-video content (readings, HTML) as complete
• Skip videos you’ve already watched elsewhere
• Track progress through text-based lessons

​

Progress Indicators

• Module headers show progress: “5/12 clases”
• Progress bars show percentage completion
• Class numbers change to checkmarks (✓) when complete

• Active class shows play icon (▶)
• Complete classes show checkmark (✓)
• Not started classes show class number

• Progress rings display completion percentage
• “X% completado” text shows exact progress
• Completed/remaining class counts

​

Local Storage (Browser)

​

localStorage Implementation

{
  "0|1|2|0|0": {
    "status": "complete",
    "completedAt": "2024-03-15T10:30:00.000Z"
  },
  "0|1|2|0|1": {
    "status": "in_progress",
    "lastWatched": "2024-03-15T10:32:00.000Z",
    "watchTime": 45.2
  }
}

​

Advantages of localStorage

​

localStorage Limitations

​

Server Synchronization

​

Automatic Sync

• Any progress change (complete, in-progress)
• Debounced to 400ms to batch updates
• Saves to /api/progress endpoint

• Saves to progress.json file on server
• Acts as backup and cross-device sync
• Survives browser cache clearing

​

Sync Strategy

// Progress change triggers sync queue
queueServerSync() {
  clearTimeout(this._syncTimer);
  this._syncTimer = setTimeout(() => {
    saveServerProgress();
  }, 400);
}

• Batches rapid changes (e.g., marking multiple classes complete)
• Reduces server load
• Prevents race conditions

​

Server Progress Backup

{
  "0|1|2|0|0": {
    "status": "complete",
    "completedAt": "2024-03-15T10:30:00.000Z"
  },
  "0|1|2|0|1": {
    "status": "in_progress",
    "lastWatched": "2024-03-15T10:32:00.000Z",
    "watchTime": 45.2
  }
}

​

Progress Merging

​

Conflict Resolution

1. Status Rank: complete > in_progress > not_started
2. Timestamp: Newer timestamp wins if status is equal

mergeProgress(localProgress, serverProgress) {
  // Combine all keys from both sources
  // For each key:
  //   - If only in one source: use that record
  //   - If in both: compare status rank
  //   - If equal rank: use newer timestamp
}

// Local: in_progress at 10:30
// Server: complete at 10:25
// Result: complete (higher status rank)

// Local: complete at 10:30
// Server: complete at 10:25  
// Result: complete at 10:30 (newer timestamp)

​

Initialization Merge

await state.init();
// 1. Load courses data
// 2. Load local progress from localStorage
// 3. Load server progress from /api/progress
// 4. Merge using conflict resolution
// 5. Save merged result to localStorage
// 6. Don't sync back to server immediately (already merged)

​

Progress Calculation

​

Course Progress

const completed = countCourseCompleted(catIdx, routeIdx, courseIdx);
const total = countCourseClasses(course);
const percent = total > 0 ? (completed / total) * 100 : 0;

• Courses with detailed class arrays
• Courses with only class counts (bootstrap mode)
• Empty courses (0% progress)

​

Route Progress

getRouteProgress(catIdx, routeIdx) {
  // If route is a course: calculate course progress
  // If route has multiple courses:
  //   - Sum all completed classes across courses
  //   - Sum all total classes across courses
  //   - Calculate overall percentage
}

​

Overall Progress

getOverallProgress() {
  return {
    totalClasses,        // Total classes across all courses
    completedClasses,    // Total completed classes
    totalRoutes,         // Total learning paths
    startedRoutes,       // Routes with >0 completed
    completedRoutes,     // Routes with 100% completion
    percent              // Overall completion percentage
  }
}

​

Progress Views

​

Course Detail Page

     ╭─────╮
    │  75% │   15 completadas
     ╰─────╯   5 restantes

• Large circular progress indicator
• Percentage displayed in center
• Completion stats below
• Ring turns green when 100% complete

• Mini progress bars on each module header
• “X/Y” class count
• Checkmark (✅) on module number when 100% complete

​

Learning View

┌─────────────────────────────────┐
│ 📊 Desarrollo Web               │
│ Curso de JavaScript Avanzado    │
│                                 │
│    ╭──────╮                     │
│   │  45% │  Continuar →         │
│    ╰──────╯                     │
│ 18/40 clases completadas        │
└─────────────────────────────────┘

​

Player Sidebar

• Active: ▶ Class Name
• Complete: ✓ Class Name (styled with completion color)
• Not Started: 1 Class Name (number badge)

[1] Module Name
    5/8 clases

​

Notes and Personal Tracking

​

Course Notes

• Large textarea for notes, code snippets, ideas
• Auto-saves to localStorage on input
• Persists per course (unique storage key)
• Supports markdown-style text

const notesKey = `platzi_notes_${catIdx}_${routeIdx}_${courseIdx}`;

• Take notes during video lessons
• Save code snippets for reference
• Track personal insights
• Create quick reference guides

​

API Endpoints

​

Get Progress

GET /api/progress

{
  "0|1|2|0|0": {
    "status": "complete",
    "completedAt": "2024-03-15T10:30:00.000Z"
  }
}

​

Save Progress

POST /api/progress
Content-Type: application/json

{
  "0|1|2|0|0": {
    "status": "complete",
    "completedAt": "2024-03-15T10:30:00.000Z"
  }
}

​

Cross-Device Progress

​

Syncing Across Devices

1. Same Server Required: All devices must connect to the same server
2. Automatic Sync: Progress syncs on each change
3. Merge on Load: Opening the app merges server progress
4. No Manual Sync Needed: Everything is automatic

Device A: Mark class complete
  → Save to localStorage
  → Sync to server (progress.json)

Device B: Open app
  → Load local progress
  → Load server progress
  → Merge (server wins if newer)
  → Continue learning

​

Progress Persistence

• Browser restarts
• Server restarts (saved to progress.json)
• Network interruptions (localStorage backup)

• Browser cache/data clearing (unless synced to server)
• Changing to different server
• Deleting progress.json on server

​

Privacy and Data

​

What’s Tracked

​

What’s NOT Tracked

​

Data Location

• localStorage: Your browser’s local storage
• Server: progress.json file in server directory
• Not Sent: No external services, no analytics, no telemetry

​

Troubleshooting Progress

​

Progress Not Saving

1. Browser console for errors
2. localStorage availability (private browsing may block)
3. Server connectivity (/api/health)
4. Disk space on server for progress.json

​

Progress Lost After Browser Clear

• Progress should restore from server on next load
• If server progress was also lost, it cannot be recovered
• Recommendation: Don’t clear browser data unnecessarily

​

Syncing Issues

1. /api/progress endpoint returns data
2. POST requests succeed (check Network tab)
3. Server has write permissions for progress.json
4. Check server logs for sync errors

​

Progress Not Merging

1. Server progress loads successfully on init
2. No errors during merge (check console)
3. localStorage has space available
4. Timestamps are valid ISO 8601 format

​

Best Practices

1. Let Auto-Tracking Work: Videos auto-complete on finish
2. Manual Complete for Non-Video: Use button for readings/HTML content
3. Use Notes Feature: Track insights and code snippets per course
4. Check Learning View: Monitor overall progress regularly
5. Don’t Clear Browser Data: If you must, ensure server sync is working
6. Multiple Devices: Wait a few seconds after completing to ensure sync

​

Technical Details

​

State Management

• markClassComplete(classKey) - Mark class as complete
• markClassInProgress(classKey, time) - Mark class as in progress
• isClassComplete(classKey) - Check completion status
• getClassStatus(classKey) - Get current status
• getCourseProgress(catIdx, routeIdx, courseIdx) - Calculate course progress
• getRouteProgress(catIdx, routeIdx) - Calculate route progress

​

Progress Data Schema

interface ProgressRecord {
  status: 'complete' | 'in_progress' | 'not_started';
  completedAt?: string;      // ISO 8601 timestamp
  lastWatched?: string;      // ISO 8601 timestamp  
  watchTime?: number;        // seconds
}

interface ProgressData {
  [classKey: string]: ProgressRecord;
}

​

Performance Considerations

• Debounced Sync: 400ms delay batches rapid changes
• Minimal Server Calls: Only on actual progress changes
• localStorage First: Instant reads, no network latency
• Efficient Merging: O(n) merge algorithm on initialization
• No Polling: Server doesn’t poll for updates (push-based)