ryan/lunarfront-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
lunarfront-app/planning/05_Domain_Lessons.md
Ryan Moon 5f8726ee4e Add planning documents for Forte music store platform 
17 domain design docs covering architecture, accounts, inventory,
rentals, lessons, repairs, POS, payments, batch repairs, delivery,
billing, accounting, deployment, licensing, installer, and backend
tech architecture. Plus implementation roadmap (doc 18) and
personnel management (doc 19).

Key design decisions documented:
- company/location model (multi-tenant + multi-location)
- member entity (renamed from student to support multiple adults)
- Stripe vs Global Payments billing ownership differences
- User/location/terminal licensing model
- Valkey 8 instead of Redis
2026-03-27 14:51:23 -05:00

827 lines
14 KiB
Markdown
Raw Permalink Blame History

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
Reference in New Issue View Git Blame Copy Permalink