Assignment System Implementation¶

Overview¶

Complete implementation of the teacher assignment system where teachers can assign music pieces to students with deadlines, practice goals, and tracking capabilities.

Database Schema¶

Assignment Table¶

CREATE TABLE assignment (
    id INT AUTO_INCREMENT PRIMARY KEY,
    teacher_id INT NOT NULL,
    student_id INT DEFAULT NULL,
    class_id INT DEFAULT NULL,
    music_piece_id INT NOT NULL,
    title VARCHAR(255) NOT NULL,
    description LONGTEXT,
    assigned_at DATETIME NOT NULL,
    due_at DATETIME NOT NULL,
    status VARCHAR(20) NOT NULL,
    practice_goal JSON DEFAULT NULL,
    completed_at DATETIME DEFAULT NULL,
    teacher_feedback LONGTEXT DEFAULT NULL,
    grade VARCHAR(50) DEFAULT NULL,
    created_at DATETIME NOT NULL,
    FOREIGN KEY (teacher_id) REFERENCES user (id),
    FOREIGN KEY (student_id) REFERENCES user (id),
    FOREIGN KEY (class_id) REFERENCES class (id),
    FOREIGN KEY (music_piece_id) REFERENCES music_piece (id)
);

Indexes: - teacher_id - Find assignments by teacher - student_id - Find assignments for student - class_id - Find class assignments - music_piece_id - Find assignments for specific piece

Practice Plan Steps Relationship¶

Assignments can include structured practice steps for guided learning:

-- Many-to-many relationship with PracticePlanStep
CREATE TABLE assignment_practice_plan_step (
    assignment_id INT NOT NULL,
    practice_plan_step_id INT NOT NULL,
    PRIMARY KEY (assignment_id, practice_plan_step_id),
    FOREIGN KEY (assignment_id) REFERENCES assignment (id) ON DELETE CASCADE,
    FOREIGN KEY (practice_plan_step_id) REFERENCES practice_plan_step (id) ON DELETE CASCADE
);

Assignment with Practice Steps: - Teacher selects specific practice steps to assign - Steps define loop ranges, tempo targets, loop counts, durations - Student practices with auto-initialized Practice Assistant - Progress tracked per step (loops completed, time spent, tempo reached)

See PRACTICE_ASSISTANT_GUIDE.md for complete documentation.

Entity: Assignment¶

Location: src/Entity/Assignment.php

Fields¶

teacher: User who created the assignment (required)
student: Individual student (nullable for class assignments)
class: Class for group assignments (nullable)
musicPiece: The music piece to practice (required)
title: Assignment name (e.g., "Practice Measures 1-16")
description: Additional instructions
assignedAt: When assignment was created
dueAt: Deadline
status: Current status (assigned, in_progress, completed, overdue)
practiceGoal: JSON object with:
targetTime: Minutes to practice
targetAccuracy: Percentage accuracy goal
specificMeasures: Which sections to focus on
practicePlanSteps: Collection - Structured practice steps (optional)
completedAt: When student submitted
teacherFeedback: Teacher's feedback after review
grade: Grade or evaluation (A, B+, 95%, etc.)
createdAt: Timestamp

Practice Plan Steps Integration:

When an assignment includes practicePlanSteps: - Students see Practice Assistant auto-load when practicing - Each step has specific goals (loop range, tempo, loops, duration) - Progress tracked automatically per step - Teacher can view step-by-step progress analytics - Students cannot modify teacher's practice plan

Helper Methods¶

isOverdue(): Check if past due date
isCompleted(): Check if status is completed
isInProgress(): Check if currently being worked on
getDaysUntilDue(): Days remaining (negative if overdue)
getAssignmentType(): Returns 'class' or 'individual'
hasPracticePlanSteps(): Check if assignment includes practice steps
getPracticePlanSteps(): Get collection of practice steps
addPracticePlanStep(PracticePlanStep $step): Add practice step to assignment
removePracticePlanStep(PracticePlanStep $step): Remove practice step

Automatic Status Updates¶

The @PrePersist and @PreUpdate lifecycle callbacks automatically update status to 'overdue' when the due date passes.

Repository: AssignmentRepository¶

Location: src/Repository/AssignmentRepository.php

Query Methods¶

1. `findByTeacher(User $teacher, ?string $status, ?User $student, ?ClassEntity $class)`¶

Find all assignments created by a teacher with optional filters.

$assignments = $assignmentRepo->findByTeacher($teacher, 'active', null, null);

2. `findByStudent(User $student, ?string $status)`¶

Find all assignments for a student (both direct and through classes).

$assignments = $assignmentRepo->findByStudent($student, 'completed');

3. `findActiveByStudent(User $student)`¶

Find active assignments (assigned, in_progress, or overdue).

$activeAssignments = $assignmentRepo->findActiveByStudent($student);

4. `findOverdue()`¶

Find all overdue assignments across the system.

$overdueAssignments = $assignmentRepo->findOverdue();

5. `findDueSoon(int $daysAhead = 2)`¶

Find assignments due within specified days.

$dueSoon = $assignmentRepo->findDueSoon(2); // Due in next 2 days

6. `getTeacherStats(User $teacher)`¶

Get assignment statistics for a teacher.

Returns:

[
    'total' => 45,
    'assigned' => 12,
    'in_progress' => 18,
    'completed' => 10,
    'overdue' => 5
]

7. `getStudentStats(User $student)`¶

Get assignment statistics for a student.

8. `findByMusicPiece(MusicPiece $piece)`¶

Find all assignments for a specific music piece.

9. `updateOverdueStatus()`¶

Batch update all overdue assignments (useful for cron jobs).

$count = $assignmentRepo->updateOverdueStatus(); // Returns number updated

10. `calculateProgress(Assignment $assignment)`¶

Calculate student's progress on assignment based on practice sessions.

Returns:

[
    'totalMinutes' => 45,
    'targetTime' => 60,
    'timeProgress' => 75.0,
    'targetAccuracy' => 90,
    'accuracyProgress' => 0,
    'sessionCount' => 8,
    'isComplete' => false
]

Teacher Routes¶

1. Assignment List - `/teacher/assignments`¶

Method: GET
Route Name: teacher_assignments

Lists all teacher's assignments with filtering options.

Query Parameters: - status: Filter by status (assigned, in_progress, completed, overdue) - student: Filter by student ID - class: Filter by class ID

Template: templates/teacher/assignments.html.twig

Features: - Statistics cards (total, active, completed, overdue) - Filter form (status, student, class) - Assignments table with status badges - Days until due calculations - View assignment detail links

2. Create Assignment - `/teacher/assignments/create`¶

Methods: GET, POST
Route Name: teacher_assignment_create

Create new assignment for individual student or entire class.

POST Data: - assignment_type: 'individual' or 'class' - student_id: For individual assignments - class_id: For class assignments - piece_id: Music piece ID (required) - title: Assignment title (required) - description: Instructions (optional) - due_date: Deadline (required) - target_time: Practice minutes goal (optional) - target_accuracy: Accuracy percentage goal (optional) - specific_measures: Sections to focus on (optional)

Template: templates/teacher/assignment_create.html.twig

Features: - Radio buttons for individual vs. class selection - Dynamic form fields based on selection - Music piece dropdown - Practice goals section - Date picker with default 7 days ahead - Tips sidebar

Bulk Assignment: When assigning to a class, the system creates individual assignments for each active student in the class.

3. Assignment Detail - `/teacher/assignments/{id}`¶

Method: GET
Route Name: teacher_assignment_detail

View assignment details with student progress.

Template: templates/teacher/assignment_detail.html.twig

Features: - Assignment overview - Progress bars for practice goals - Practice session statistics - Teacher feedback form - Grade input - Recent practice sessions list - Quick action links

4. Add Feedback - `/teacher/assignments/{id}/feedback`¶

Method: POST
Route Name: teacher_assignment_feedback

Add or update teacher feedback and grade.

POST Data: - feedback: Text feedback - grade: Grade/evaluation

Response: JSON or redirect

5. Delete Assignment - `/teacher/assignments/{id}/delete`¶

Method: POST
Route Name: teacher_assignment_delete

Delete an assignment (with confirmation).

Student Routes¶

1. Assignment List - `/student/assignments`¶

Method: GET
Route Name: student_assignments

View all student's assignments with tabs.

Query Parameters: - tab: 'active', 'completed', or 'overdue'

Template: templates/student/assignments.html.twig

Features: - Statistics cards - Tab navigation - Assignment cards with status indicators - Days until due warnings - Progress bars (if target time set) - Direct practice links

2. Assignment Detail - `/student/assignments/{id}`¶

Method: GET
Route Name: student_assignment_detail

View assignment details and progress.

Template: templates/student/assignment_detail.html.twig

Features: - Status alerts (overdue, due soon, completed) - Assignment details - Progress visualization - Practice goal tracking - Teacher feedback display - Submit assignment button - Recent practice sessions - Direct practice link

3. Submit Assignment - `/student/assignments/{id}/submit`¶

Method: POST
Route Name: student_assignment_submit

Mark assignment as completed.

Response: JSON

{
    "success": true,
    "message": "Assignment submitted successfully!"
}

Actions: - Sets status to 'completed' - Sets completedAt timestamp - TODO: Sends notification to teacher

4. Mark In Progress - `/student/assignments/{id}/mark-in-progress`¶

Method: POST
Route Name: student_assignment_mark_progress

Update status from 'assigned' to 'in_progress'.

Response: JSON

UI Components¶

Teacher Templates¶

assignments.html.twig
Statistics dashboard
Filter form
Assignments table
Status badges
Date formatting
assignment_create.html.twig
Type selection (radio buttons)
Dynamic student/class selector
Music piece dropdown
Practice goals form
JavaScript for field toggling
assignment_detail.html.twig
Overview card
Progress visualization
Feedback form
Practice sessions list
Quick actions sidebar

Student Templates¶

assignments.html.twig
Statistics cards
Tab navigation
Assignment list
Status indicators
Due date warnings
assignment_detail.html.twig
Alert banners (overdue/due soon)
Progress bars
Teacher feedback section
Submit button with JavaScript
Practice sessions

Status Flow¶

ASSIGNED
   ↓
   │ (Student clicks "Mark as In Progress")
   ↓
IN_PROGRESS
   ↓
   │ (Student clicks "Submit Assignment")
   ↓
COMPLETED

Automatic Status: - OVERDUE: Automatically set when due_at < now AND status != 'completed'

Practice Goal Tracking¶

Goals are stored in JSON format:

{
    "targetTime": 60,
    "targetAccuracy": 90,
    "specificMeasures": "Measures 1-16, 24-32"
}

Progress Calculation:

The calculateProgress() method: 1. Queries PracticeSession table for sessions since assignment date 2. Filters by music piece and student 3. Sums total practice minutes 4. Calculates percentage toward target 5. Counts total sessions

Notifications (TODO)¶

The following notifications should be implemented:

Assignment Created
Send email to student(s)
Include assignment details and link
Due Soon Reminders
2 days before due date
On due date
Assignment Submitted
Notify teacher
Include link to review
Feedback Added
Notify student
Include grade and feedback

Implementation: Create AssignmentNotificationService that uses MailerInterface.

Access Control¶

Teacher Access¶

Can only view/edit their own assignments
Can create assignments for their students or classes
Can view student progress on their assignments

Student Access¶

Can view assignments assigned directly to them
Can view assignments for classes they're enrolled in
Cannot view other students' assignments
Can submit their own assignments

Verification: All controllers check ownership before allowing access.

Future Enhancements¶

Recurring Assignments
Weekly practice assignments
Template-based creation
Assignment Templates
Save common assignment configurations
Quick creation from templates
Peer Review
Students review each other's work
Teacher moderation
Video Submissions
Students record performance
Attach to assignment submission
Rubrics
Detailed grading criteria
Automatic scoring
Assignment Analytics
Completion rates
Average practice time
Success metrics

Testing Checklist¶

Teacher Workflows¶

Student Workflows¶

System Functions¶

Integration Points¶

With Existing Features¶

Music Pieces
Assignments reference MusicPiece entity
Can filter pieces available for assignment
Practice Sessions
Progress calculated from PracticeSession records
Sessions linked by music_piece_id and user_id
Teacher-Student Relationships
Assignment creation validates relationship
Only assigned students can view
Classes
Bulk assignment to class members
Class-wide assignments
Organizations
Could add organization-level assignment visibility
Org admins could view all assignments

Database Queries Performance¶

Recommended Indexes (already created): - assignment(teacher_id) - Teacher assignment queries - assignment(student_id) - Student assignment queries - assignment(class_id) - Class assignment queries - assignment(music_piece_id) - Piece assignment queries - assignment(status) - Status filtering - assignment(due_at) - Overdue checks

Query Optimization: - Use eager loading for relationships when listing assignments - Cache statistics results - Batch update overdue status via cron job instead of on-the-fly

Usage Examples¶

Create Individual Assignment¶

$assignment = new Assignment();
$assignment->setTeacher($teacher);
$assignment->setStudent($student);
$assignment->setMusicPiece($piece);
$assignment->setTitle('Practice Scales');
$assignment->setDueAt(new \DateTime('+7 days'));
$assignment->setTargetTime(30);

$entityManager->persist($assignment);
$entityManager->flush();

Create Class Assignment¶

$class = $classRepository->find($classId);
$members = $classMemberRepository->findBy(['class' => $class, 'status' => 'active']);

foreach ($members as $member) {
    $assignment = new Assignment();
    $assignment->setTeacher($teacher);
    $assignment->setStudent($member->getStudent());
    $assignment->setClass($class);
    $assignment->setMusicPiece($piece);
    $assignment->setTitle('Weekly Practice');
    $assignment->setDueAt(new \DateTime('+7 days'));

    $entityManager->persist($assignment);
}

$entityManager->flush();

Check Progress¶

$progress = $assignmentRepository->calculateProgress($assignment);

if ($progress['isComplete']) {
    // Student met the goal
    echo "Goal achieved! {$progress['totalMinutes']} minutes practiced.";
}

Implementation Date: January 16, 2026
Status: ✅ Complete
Database: ✅ Migrated
Files Created: 7
Routes Added: 10