Course Progress Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use compose:subagent (recommended) or compose:execute to implement this plan task-by-task.

Goal: Add lesson completion tracking — mark complete/incomplete, progress indicators, sequential gating UI.

Architecture: Progress via PATCH /courses/{id}/lessons/{id}/progress with { status: "completed"|"incomplete" }. Progress data embedded in section/lesson responses.

Tech Stack: React 19, TanStack Router, TanStack React Query

---

File Structure

src/
├── lib/api/
│   └── courses.ts                       # Course progress API hooks
├── components/courses/
│   ├── LessonPlayer.tsx                 # Enhanced lesson player with progress
│   ├── SectionSidebar.tsx               # Section/lesson navigation with progress
│   └── CourseProgressBar.tsx            # Overall course progress bar
├── routes/courses/
│   ├── $courseId.tsx                    # Enhanced course page
│   └── $courseId/
│       └── $lessonId.tsx               # Enhanced lesson page

---

Task 1: Course Progress API Hooks

Files:

• Create: src/lib/api/courses.ts

• [ ] Step 1: Create course API layer

Hooks:

• useMarkLessonComplete(courseId, lessonId) — PATCH /api/headless/v1/courses/{courseId}/lessons/{lessonId}/progress with
• useMarkLessonIncomplete(courseId, lessonId) — PATCH with
• useToggleLessonProgress(courseId, lessonId, currentStatus) — calls complete or incomplete based on current status

Types:

type LessonProgress = { status: "incomplete" | "completed" };

• [ ] Step 2: Commit

---

Task 2: CourseProgressBar Component

Files:

• Create: src/components/courses/CourseProgressBar.tsx

• [ ] Step 1: Create progress bar

Props: sections (array with lessons)

Calculates: total lessons, completed lessons, percentage.

Display:

• Progress text: "X de Y aulas concluídas"

• Gradient progress bar

• Percentage badge

• [ ] Step 2: Commit

---

Task 3: Enhanced Lesson Page

Files:

• Modify: src/routes/courses/$courseId/$lessonId.tsx

• [ ] Step 1: Add progress toggle

Add "Marcar como concluída" / "Desmarcar" button below the lesson content. Use useToggleLessonProgress. Show current progress status.

• [ ] Step 2: Commit

---

Task 4: Enhanced Course Page

Files:

• Modify: src/routes/courses/$courseId.tsx

• [ ] Step 1: Add progress bar and completion status

Add CourseProgressBar at the top. Show completion checkmarks on each lesson in the section list.

• [ ] Step 2: Commit

---

Task 5: Verify Build

• [ ] Step 1: Run typecheck
• [ ] Step 2: Run build
• [ ] Step 3: Fix any issues