WrestleDesk/docs/superpowers/specs/2026-03-22-homework-integration-design.md

Homework System Integration - Design Spec

Overview

The backend has a complete homework system with exercises, assignments, and completion tracking. The frontend currently only supports basic CRUD. This spec covers integrating all backend features into the frontend.

---

Backend Models

1. Homework - Template with title, description, due_date, exercises
2. HomeworkExerciseItem - Links exercises to homework with reps/time
3. HomeworkAssignment - Assigns homework to wrestlers
4. HomeworkAssignmentItem - Tracks completion of each exercise
5. HomeworkStatus - Overall completion status

---

Frontend Integration

1. Update Types (lib/api.ts)

Add missing types:

interface IHomeworkExerciseItem {
  id: number
  exercise: number
  exercise_name: string
  reps: number | null
  time_minutes: number | null
  order: number
}

interface IHomework {
  id: number
  title: string
  description: string
  club: number
  club_name: string
  due_date: string
  is_active: boolean
  exercise_items: IHomeworkExerciseItem[]
  exercise_count: number
  created_at: string
  updated_at: string
}

interface IHomeworkAssignment {
  id: number
  homework: number
  homework_title: string
  wrestler: number
  wrestler_name: string
  club: number
  club_name: string
  due_date: string
  notes: string
  is_completed: boolean
  completion_date: string | null
  items: IHomeworkAssignmentItem[]
  created_at: string
}

interface IHomeworkAssignmentItem {
  id: number
  exercise: number
  exercise_name: string
  is_completed: boolean
  completion_date: string | null
}

2. Homework Page - Template Management

Exercise Selection:

• When creating/editing homework, allow selecting exercises from the exercise list
• Each exercise can have reps (for rep-based) or time_minutes (for time-based)
• Drag to reorder exercises

API Integration:

• GET /homework/{id}/exercise-items/ - Get exercises for homework
• POST /homework/{id}/exercise-items/ - Add exercise to homework
• DELETE /homework/{id}/exercise-items/{item_id}/ - Remove exercise

3. Assignments Page - View Assigned Homework

Create a new tab/section for viewing assignments:

• GET /homework/assignments/ - List all assignments
• Filter by: homework, wrestler, completion status
• Show completion progress (e.g., "3/5 exercises completed")

Assignment Detail:

• View all exercises in the assignment
• Mark individual exercises as complete
• POST /homework/assignments/{id}/complete-item/ - Mark exercise complete

4. Update Distribute Flow

Current: Select wrestlers, assign homework New:

1. Select wrestlers (filtered by club + groups)
2. Due date is set per assignment
3. Creates HomeworkAssignment with all exercise items

---

UI Components

Homework Templates Tab

• List all homework templates
• Create/Edit with exercise selection
• Delete template

My Homework Tab (for wrestlers)

• View assigned homework
• Track completion per exercise
• Due dates

Assignment Management Tab (for trainers)

• View all assignments
• Filter by status (pending/completed/overdue)
• Track which wrestlers completed

---

Data Flow

1. Trainer creates Homework template with exercises
2. Trainer assigns homework to wrestlers (filtered by group)
3. System creates HomeworkAssignment for each wrestler
4. Wrestlers see assignments and mark exercises complete
5. Trainers can track completion rates

---

Technical Approach

Frontend Pages:

• /homework - Templates list
• /homework/assignments - Assignments list (new)
• /homework/[id]/edit - Edit template with exercises

Key Changes:

• Update IHomework type with exercise_items
• Add exercise selection UI to homework form
• Create assignments list view
• Add completion tracking

API Endpoints Used:

• GET/POST /homework/ - CRUD templates
• GET/POST /homework/{id}/exercise-items/ - Manage exercises
• POST /homework/{id}/assign/ - Assign to wrestlers
• GET /homework/assignments/ - List assignments
• POST /homework/assignments/{id}/complete-item/ - Mark complete