Music Store Management Platform Domain Design: Lessons Version 1.2 | Updated: Session notes, grading scales, lesson plans, parent portal # 1. Overview The Lessons domain manages instructor scheduling, student enrollments, attendance tracking, and recurring lesson billing. Version 1.2 adds a complete teaching toolkit: per-session notes, custom grading scales, structured lesson plans with curriculum tracking, and homework assignment. These features turn the lessons module from a billing tool into a genuine teaching platform that instructors and parents will actively use. # 2. Feature Summary Feature Description Visible To Session notes — internal Instructor private notes per lesson. Not shared with student or parent. Instructor, Admin Session notes — student Shareable lesson summary — what was covered, progress comments. Instructor, Student, Parent Homework assignment Practice instructions assigned after each lesson. Instructor, Student, Parent Topics covered Tags for what was worked on — links to lesson plan items. Instructor, Admin Custom grading scales Store or instructor-defined scales. Letter, numeric, descriptive, or music-specific. Instructor, Admin Lesson plans Structured curriculum per student. Sections, items, status, grades. Instructor, Student, Parent Progress tracking Mastered / in progress / not started per curriculum item. History of grades. Instructor, Student, Parent Parent portal Parents see plan progress, session summaries, homework, and grade history. Parent via portal # 3. Core Entities ## 3.1 instructor id, company_id, employee_id (FK), display_name, bio,instruments (text[]), is_active, created_at ## 3.2 lesson_type id, company_id, name, instrument, duration_minutes,lesson_format (private|group), base_rate_monthly, created_at ## 3.3 schedule_slot id, company_id, instructor_id, lesson_type_id,day_of_week, start_time, room, max_students,is_active, created_at ## 3.4 enrollment Column Type Notes id uuid PK company_id uuid FK member_id uuid FK The member taking lessons account_id uuid FK The billing account schedule_slot_id uuid FK instructor_id uuid FK Denormalized for query convenience status enum active | paused | cancelled | completed start_date date end_date date Null for open-ended monthly_rate numeric(10,2) Actual rate billing_group varchar Consolidation group stripe_subscription_id varchar stripe_subscription_item_id varchar Line item if consolidated makeup_credits integer Available makeup credits active_lesson_plan_id uuid FK Current lesson plan for this enrollment notes text Enrollment-level notes legacy_id varchar AIM enrollment ID created_at timestamptz ## 3.5 lesson_session Column Type Notes id uuid PK enrollment_id uuid FK company_id uuid FK scheduled_date date scheduled_time time actual_start_time time Nullable — if late start noted actual_end_time time Nullable — if early end noted status enum scheduled | attended | missed | makeup | cancelled instructor_notes text Internal only — not visible to student or parent member_notes text Shareable lesson summary homework_assigned text Practice instructions for next session next_lesson_goals text What to focus on next lesson topics_covered text[] Free tags: scales, sight-reading, repertoire, theory makeup_for_session_id uuid FK Self-ref — if this is a makeup session notes_completed_at timestamptz When instructor finished post-lesson notes created_at timestamptz # 4. Custom Grading Scales Every store can define their own grading scales. Scales can be assigned at the store level (default for all instructors) or at the instructor level (personal preference). Individual lesson plan items can reference any available scale. ## 4.1 grading_scale Column Type Notes id uuid PK company_id uuid FK name varchar e.g. 'Standard Letter', 'ABRSM Style', 'Music Progress' description text Optional explanation of the scale is_default boolean Default scale used when none specified on plan item created_by uuid FK Instructor or admin who created is_active boolean created_at timestamptz ## 4.2 grading_scale_level Column Type Notes id uuid PK grading_scale_id uuid FK value varchar The grade value: A, 4, Distinction, Mastered label varchar Longer description shown in UI numeric_value integer 1-100 for averaging and reporting color_hex char(7) UI display color e.g. #4CAF50 for green sort_order integer Display order — highest grade first ## 4.3 Seeded Default Scales Scale Name Levels Standard Letter A+ A A- B+ B B- C+ C D F Numeric 1-10 10 9 8 7 6 5 4 3 2 1 ABRSM Style Distinction Merit Pass Below Pass Progress Mastered Proficient Developing Beginning Concert Readiness Concert Ready Performance Ready Practice Ready Learning Simple Excellent Good Needs Work All default scales are seeded at store creation and can be modified or deactivated. Custom scales can be added at any time. Scale levels cannot be deleted if they have been used in a graded item — only deactivated. # 5. Lesson Plans A lesson plan is a structured curriculum for a specific student enrollment. It is organized into sections (e.g. Scales, Repertoire, Theory) with individual items in each section. Each item tracks status, grade, and progress history. Multiple plans can exist per student — one active at a time per enrollment. ## 5.1 member_lesson_plan Column Type Notes id uuid PK company_id uuid FK member_id uuid FK enrollment_id uuid FK created_by uuid FK Instructor who created the plan title varchar e.g. 'Year 2 Piano', 'Grade 3 Violin' description text Goals and context for this plan template_id uuid FK Nullable — if created from a plan template is_active boolean Only one plan active per enrollment at a time started_date date completed_date date Nullable — set when all items mastered created_at timestamptz updated_at timestamptz ## 5.2 lesson_plan_section id, lesson_plan_id (FK), title, description,sort_order, created_atExample sections: Scales & Arpeggios Repertoire Theory Technique Sight Reading Ear Training ## 5.3 lesson_plan_item Column Type Notes id uuid PK section_id uuid FK title varchar e.g. 'C Major Scale 2 octaves', 'Fur Elise' description text Additional detail or context status enum not_started | in_progress | mastered | skipped grading_scale_id uuid FK Nullable — which scale to use for this item current_grade_value varchar Most recent grade assigned target_grade_value varchar Grade required to mark as mastered started_date date When first worked on mastered_date date When marked mastered notes text Instructor notes specific to this item sort_order integer created_at timestamptz updated_at timestamptz ## 5.4 lesson_plan_item_grade_history Every grade assigned to a plan item is preserved. This builds a complete history of how a student progressed through each piece or skill over time. id, lesson_plan_item_id (FK),lesson_session_id (FK nullable), -- which session this grade was givengrade_value, -- the gradegrading_scale_id (FK),graded_by (uuid FK), -- instructornotes, -- context for this gradecreated_at ## 5.5 lesson_session_plan_item Links lesson sessions to the plan items worked on during that session. Enables the full history of when each curriculum item was practiced. id, lesson_session_id (FK), lesson_plan_item_id (FK),was_worked_on (boolean),grade_value (varchar nullable), -- grade if assessed this sessiongrading_scale_id (FK nullable),notes (text nullable), -- session-specific notes on this itemcreated_at # 6. Lesson Plan Templates Instructors can save lesson plan structures as templates to quickly create plans for new students. A template defines the sections and items without any student-specific data. Templates can be shared across the store or kept private to an instructor. lesson_plan_template id, company_id, created_by (FK), title, instrument, skill_level (beginner|intermediate|advanced), description, is_shared (boolean), created_atlesson_plan_template_section id, template_id (FK), title, sort_orderlesson_plan_template_item id, section_id (FK), title, description, suggested_grading_scale_id (FK nullable), sort_order When creating a new lesson plan from a template, all sections and items are copied to the new plan. Changes to the plan after creation do not affect the template. # 7. Example — Year 2 Piano Plan Student: Emma Chen Instrument: PianoPlan: Year 2 Piano Status: Active Progress: 40%SCALES & ARPEGGIOS [done] C Major 2 octaves Mastered Oct 2024 [done] G Major 2 octaves Mastered Nov 2024 [>> ] D Major 2 octaves In Progress Grade: B [ ] A Major 2 octaves Not Started [ ] C Major arpeggio Not StartedREPERTOIRE [done] Minuet in G (Bach) Mastered Sep 2024 [>> ] Fur Elise (Beethoven) In Progress Grade: B+ [ ] Moonlight Sonata Mvt 1 Not Started [ ] Sonatina Op.36 No.1 Not StartedTHEORY [done] Key signatures to 2 sharps Mastered [>> ] Intervals - 3rds and 6ths In Progress [ ] Chord inversions Not StartedTECHNIQUE [>> ] Hanon exercises 1-10 In Progress [ ] Scales in thirds Not StartedLast lesson (Nov 15): Topics: Fur Elise bars 1-16, D Major scale Homework: Practice Fur Elise bars 1-8 hands together daily Notes for parent: Great focus today. Right hand is clean. Next goals: Clean up arpeggios in bars 5-6 # 8. Instructor Post-Lesson Workflow After each lesson the instructor completes a brief post-lesson record. The UI is optimized for speed — a mobile-friendly form the instructor fills in immediately after the student leaves. Post-Lesson Form — Emma Chen, Nov 15Topics covered today: [+ Add from plan] [x] Fur Elise (Beethoven) Grade: [B+ v] [x] D Major 2 octaves Grade: [B v] [+ Add custom topic]Homework assigned: Practice Fur Elise bars 1-8 hands together dailyNotes for parent/student: Great focus today. Right hand melody is clean. Left hand needs more practice on the arpeggios.Private instructor notes: Emma seems distracted lately - check in with parentNext lesson goals: Clean up bars 5-6 arpeggios. Start bars 17-24.[Save Notes] - Topics linked to plan items auto-update item status to in_progress if not_started - Grade entry creates a lesson_plan_item_grade_history record - Student notes and homework immediately visible in parent portal after save - Private instructor notes never visible outside staff views - Notes completed timestamp recorded — store can see if instructors are filling in notes # 9. Parent Portal — Lessons View Parents access the customer portal to see their child's lesson progress. The view is read-only and shows only student-facing content — never instructor private notes. Portal — Emma Chen's LessonsCurrent Enrollment: Piano with Ms. Sarah M. Tuesdays 4:00pm Next lesson: Nov 22Last Lesson Summary (Nov 15): What we worked on: Fur Elise, D Major Scale Homework: Practice Fur Elise bars 1-8 hands together daily Notes: Great focus today. Right hand melody is clean. Left hand arpeggios need more work.Lesson Plan Progress: 40% complete Scales: 2 of 5 mastered Repertoire: 1 of 4 mastered [In progress: Fur Elise] Theory: 1 of 3 mastered Technique: 0 of 2 mastered [View Full Plan]Recent Grades: Fur Elise B+ Nov 15 D Major Scale B Nov 15 Minuet in G A Sep 28 [Mastered]Upcoming Lessons: Nov 22 Tuesday 4:00pm Nov 29 Tuesday 4:00pmAttendance: 12 attended, 1 missed, 0 makeups available # 10. Business Rules ## 10.1 Notes - instructor_notes are never exposed via any API route accessible to students or parents - member_notes and homework are visible in parent portal immediately after save - notes_completed_at tracked per session — admin can identify instructors not completing notes - Notes are optional — sessions can be marked attended without post-lesson notes - Notes can be edited after save — edit history not required but updated_at tracked ## 10.2 Grading Scales - Each store gets all default scales seeded at creation - Default scale is used when a plan item has no explicit scale assigned - Scale levels used in grade history cannot be deleted — only deactivated - Numeric_value enables cross-scale average calculations in reports - Instructors can create personal scales visible only to them ## 10.3 Lesson Plans - Only one plan can be active per enrollment at a time - Completing a plan (all items mastered) does not auto-create the next plan - Plan items marked mastered record mastered_date automatically - Skipped items excluded from progress percentage calculation - Plan history preserved when enrollment ends — never deleted - Templates are copied on use — template changes do not affect existing plans - Plan visible in parent portal — instructor controls what items appear there via is_shared flag on items ## 10.4 Scheduling Constraints - Student cannot be enrolled in two slots at the same day and time - Instructor cannot teach two students simultaneously unless group lesson - Group lessons enforce max_students cap on schedule_slot - Makeup sessions linked to original missed session via makeup_for_session_id # 11. Reporting Report Description Student progress summary Plan completion % per student, items mastered, current grades Instructor notes compliance Which instructors are completing post-lesson notes and how quickly Grade distribution Grade spread per instructor, per instrument, per plan item Curriculum progress How many students are working on each plan item — popular pieces Homework completion Homework assigned vs next-session progress correlation Retention by progress Do students who have active lesson plans churn less? Correlation report. Plan template usage Which templates are used most, average completion time per template Attendance summary Attended, missed, makeup by student, instructor, and period