docs(phase7): document the business/product architecture foundation

New: ROOTNODE_ACADEMY_BUSINESS_AND_PRODUCT_ARCHITECTURE.md (canonical business/platform bridge — course families, delivery modes, BUILT NOW/PHASE 7 BUILT/FUTURE), OFFERING_AND_ REGISTRATION_MODEL.md (lifecycle diagrams, capacity mechanics), STUDENT_GUARDIAN_DATA_ MODEL.md (data minimization, RBAC, legal-review items), SCHOOL_AND_COMMUNITY_DELIVERY_ ARCHITECTURE.md (organization/location mapping, explicitly not multi-tenancy), PHASE7_PRODUCT_ARCHITECTURE.md (phase summary). Updated: WEBSITE_ENROLLMENT_INTEGRATION.md (documented future offering/registration flow, current live contract unchanged), platform/README.md (test list). Co-Authored-By: Claude Sonnet 5 <[email protected]>
2026-08-26 22:44:13 -05:00
parent 7d870d8e2b
commit df5e39f767
7 changed files with 591 additions and 4 deletions
@@ -0,0 +1,143 @@
+# RootNode Academy — Business & Product Architecture
+
+Phase 7 Step 1 — the canonical bridge between RootNode's business strategy and its platform
+architecture. This is where "what RootNode Academy sells and to whom" and "what the codebase
+actually implements" are kept in one place, deliberately separated into BUILT NOW / PHASE 7
+BUILT / FUTURE so nobody has to guess which parts are real.
+
+## Course families
+
+INIT_, COMPILE_, ROOT_, and BOOTCAMP_ are **product positioning and technical-depth families**,
+not a rigid age ladder and not a mandatory sequence:
+
+| Family | Typical audience (guidance, not a gate) | Status |
+|---|---|---|
+| INIT_ | ~ages 5-10 | Not yet authored (BUILT NOW: `programs.family` accepts it; PHASE 7 BUILT: nothing else; FUTURE: real curriculum) |
+| COMPILE_ | ~ages 11-14 | Same as INIT_ |
+| ROOT_ | ~ages 15+ through adult | **Fully authored, V1 pilot-ready** (Phase 6F) |
+| BOOTCAMP_ | short/intensive seasonal or specialty offerings | BUILT NOW: `programs.family` accepts it; PHASE 7 BUILT: the offering/curriculum-package machinery a bootcamp needs; FUTURE: an actual bootcamp program row |
+
+**INIT → COMPILE → ROOT is explicitly NOT a mandatory path.** A student's access to any given
+course depends on that course's own prerequisites (already real and server-enforced within
+ROOT_ — see `docs/ROOT_V1_PREREQUISITE_MAP.md`), not on which family they've touched before.
+
+## COMPILE_ / ROOT_ overlap
+
+These two families intentionally cover overlapping technical territory at different depths — an
+adult is not blocked from an electronics/robotics/IoT course merely because it's positioned
+under COMPILE_, and a COMPILE_-age student is not blocked from later revisiting the same domain
+at ROOT_ depth. Example: COMPILE_ might teach "ESP32 + a sensor + introductory MQTT"; ROOT_ might
+teach "Linux + networking + a real broker/service + a containerized IoT workload + observability"
+— same domain, different technical floor. **BUILT NOW**: nothing prevents this architecturally —
+`programs`/`offerings` carry no family-based authorization check anywhere in the codebase.
+**FUTURE**: the actual COMPILE_ electronics/robotics content itself (explicitly out of Phase 7's
+scope).
+
+## Program vs. Course vs. Offering
+
+Three previously-conflated levels, now distinct:
+
+- **Program** (`programs` table, Phase 5B, unchanged): the educational product/path itself —
+  e.g. "ROOT Kubernetes Foundations." Carries `family` and a default `delivery_mode`.
+- **Course** (`courses` table, Phase 6A, unchanged): a curricular unit inside a program — e.g.
+  "ROOT 02 Linux Administration & Networking."
+- **Offering** (`offerings` table, **new this phase**): a specific purchasable/enrollable
+  *instance* of delivering a program (or a curriculum-package subset of one) — e.g. "Winter
+  Break Linux & Systems Camp — December 2026," "ROOT Foundations Cohort — Spring 2027," "ROOT
+  Self-Paced." A program can have many offerings across time; an offering always points at
+  exactly one program.
+
+A **workshop** and a **cohort** are both just `delivery_mode` values on an offering, not separate
+tables — see "Delivery modes" below. A **curriculum package** (new this phase) is an optional,
+named, versioned SUBSET reference into an existing program's courses, for when an offering (like
+a camp) intentionally teaches only part of a program — see `docs/OFFERING_AND_REGISTRATION_MODEL.md`.
+
+## Age guidance, not a gate
+
+`offerings.recommended_min_age`/`recommended_max_age` and each course family's typical-audience
+description are **display/marketing guidance only**. No API authorization check anywhere in this
+codebase reads either value — enrollment and course access remain governed entirely by
+prerequisites, entitlement (`enrollments.status`), and (new this phase) offering capacity/
+registration status. Verified explicitly in `platform/test/e2e-phase7.js`.
+
+## Delivery modes
+
+Curriculum and delivery are separate concepts. `offerings.delivery_mode` (new this phase) is a
+single column supporting: `self_paced`, `cohort`, `hybrid`, `camp`, `workshop`, `school`,
+`after_school`, `homeschool`, `community`, `one_to_one`. No curriculum content is duplicated per
+mode — the same `program`/`courses`/`course_modules`/`module_activities` are read regardless of
+which offering enrolled the student into them, exactly the same principle
+`docs/REMOTE_AND_SELF_PACED_ARCHITECTURE.md` already established for self-paced vs.
+instructor-led delivery of ROOT_ V1.
+
+## Organizations and locations
+
+**Organization** (new this phase): a business/delivery relationship — a school, library,
+homeschool group, community organization, or workforce-development partner. **Not** SaaS
+multi-tenancy: RootNode Academy remains one Academy, one database, one set of students/
+instructors; an organization is metadata an offering can optionally reference, not a data
+partition. **Location** (new this phase): a physical or virtual delivery site, optionally tied
+to an organization (a rented community-center room needs no partner org; "online" needs neither
+an org nor a physical address). See `docs/SCHOOL_AND_COMMUNITY_DELIVERY_ARCHITECTURE.md`.
+
+## Guardians and minors
+
+**Guardian** (new this phase, `guardians`/`student_guardians`): a real, separate identity from a
+student's own account — not a login/auth identity yet (no password, no session), just a
+contact/relationship record. Replaces the Phase 5C `enrollments.metadata.contact_email`
+workaround as the proper foundation, while leaving that workaround functioning unchanged for
+backward compatibility with the live website integration. See
+`docs/STUDENT_GUARDIAN_DATA_MODEL.md`.
+
+## Registration, enrollment, and agreements
+
+**Registration** (new this phase, `offering_registrations`): pre-enrollment interest/application
+information for a specific offering — separate from `enrollments` (academic entitlement,
+unchanged). A registration becomes a real enrollment only once `confirmed`, via
+`convertRegistrationToEnrollment()`. **Agreement** (new this phase,
+`agreement_definitions`/`agreement_acceptances`): a versioned ACCEPTANCE RECORD, never legal
+text authored by this codebase. See `docs/OFFERING_AND_REGISTRATION_MODEL.md`.
+
+## Commerce boundary — unchanged, extended in documentation only
+
+The existing boundary (`docs/WEBSITE_ENROLLMENT_INTEGRATION.md`) stands: the website owns
+marketing/pricing/checkout, RootNode's platform owns everything after a verified commerce event.
+Phase 7 adds a documented FUTURE flow (website → offering selection → registration → checkout →
+verified commerce event → registration confirmed → enrollment activated) without implementing
+any payment code. **BUILT NOW**: the existing `/api/integrations/enrollments` endpoint,
+unchanged. **PHASE 7 BUILT**: the registration/offering model that future flow will plug into.
+**FUTURE**: an actual commerce-event webhook confirming a registration.
+
+## First commercial target: Winter Break Camp
+
+Per `docs/WINTER_BREAK_CAMP_CURRICULUM_OPTIONS.md`'s Option A (Linux & Systems Foundations,
+ROOT 01-02, ~12.4 hours), Phase 7 models this as a real, if still DRAFT, offering
+(`docs/OFFERING_AND_REGISTRATION_MODEL.md`'s worked example) — proving the platform CAN
+represent and operate it, without inventing dates, venue, price, or seat count that aren't
+already decided.
+
+## Future memberships/subscriptions and institutional delivery
+
+Recurring (self-paced subscriptions, after-school programs, school/community contracts) and
+institutional (schools, libraries, workforce partners) revenue channels are **FUTURE** — the
+`organizations`/`locations`/`offerings` model this phase builds is deliberately general enough
+to represent them later without a schema redesign, but no billing/subscription code exists or is
+planned this phase.
+
+## BUILT NOW / PHASE 7 BUILT / FUTURE — summary
+
+| Concept | Status |
+|---|---|
+| Programs, courses, ROOT_ V1 curriculum | BUILT NOW (Phases 1-6F) |
+| `programs.family` accepting `bootcamp` | PHASE 7 BUILT (schema widening only) |
+| Organizations, locations | PHASE 7 BUILT |
+| Guardians, student-guardian relationships | PHASE 7 BUILT |
+| Offerings, capacity, server-defined status transitions | PHASE 7 BUILT |
+| Curriculum packages (subset references) | PHASE 7 BUILT |
+| Registrations, registration lifecycle | PHASE 7 BUILT |
+| Agreement definitions/acceptances (record-only, no legal text) | PHASE 7 BUILT |
+| Admin routes for all of the above | PHASE 7 BUILT |
+| Admin UI (Offerings/Registrations screens) | **NOT BUILT this phase** — see known limitations |
+| Public registration flow, payments, subscriptions | FUTURE |
+| INIT_/COMPILE_ curriculum | FUTURE |
+| School/library SIS integrations, parent portal | FUTURE, explicitly out of scope |