lunarfront-app/planning/05_Domain_Lessons.md

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