lifecycle-events-architecture.md

How Lifecycle Events Work in Squash Team One

The core idea: There is no "lifecycle event" entity. An "Initial Assessment" or "Vision Development Session" is just a session template that a coach creates, fills with whatever drills and metrics they want, and optionally tags (once #63 ships) as milestone, onboarding, etc. The system doesn't know what an "Initial Assessment" is. It knows what a session template is, what a tag is, and what a due date is. The coach defines the meaning.

The flow, using only what exists today

1. Coach builds a session template in the library — specific drills, specific metrics (could be court drills with numeric metrics, reflection exercises with text prompts, or a mix)
2. Coach instantiates it for a player → creates a real session with snapshotted drills, session_template_id recording lineage, a due_at for the deadline
3. Player (or coach) does the work, records measures
4. Coach clicks "Mark Complete" → completed_at is set once, permanently
5. "Has Diego done his assessment?" is a query: find a session where session_template_id = that template, Diego is in session_profiles, and completed_at IS NOT NULL

Where modules fit (designed, not yet built — #43)

Modules are for multi-session processes. "Onboarding Program" = a module containing three session templates in order (Initial Assessment → Vision Development → Training Plan Review). Instantiating a module creates three real sessions. Progress is derived: count how many of those sessions have completed_at IS NOT NULL. No enrollment table, no assignment state — individual sessions already carry due_at and completed_at.

Where tags fit (designed, not yet built — #63)

Tags are the classification layer. They're what let the UI and intelligence layer distinguish "this is a milestone template" from "this is a regular Tuesday practice template" without hardcoding entity types. Different orgs tag things differently — same flexible mechanism.

What we decided not to build

• No module_assignments or enrollment tracking table — completion is derived from session data
• No workflow engine with states, transitions, or prerequisite gates
• No hardcoded "Initial Assessment" table or entity type
• No trigger-based completion — completed_at is set by intentional user action, and view_mode (planning/live/review) is purely a UI concern with no lifecycle semantics

The separation that makes it all work

view_mode is how you look at a session. completed_at is whether the session happened. These are independent. A coach can review a session that isn't complete. A completed session can be viewed in any mode. The intelligence layer, notifications, and milestone queries only care about completed_at.