ced4568
8b3e56e402
19/19: pricing in the public serializer, checkout gated on agreements, server-authoritative amount, webhook signature verification and idempotency, payment success/failure/abandonment, last-seat checkout race, reservation reaper, manual refund with no cascade, minor guardian routing, admin/RBAC payment-data restrictions, audit/metric hygiene, the status-lookup endpoint, and confirmation that ROOT_ V1/free-offering/classroom flows are unaffected.
177 lines
13 KiB
Markdown
177 lines
13 KiB
Markdown
# RootNode Academy — Platform
|
||
|
||
The full multi-student platform, layered on top of the Lab image at the repo root (backend/
|
||
entrypoint/Dockerfile unmodified; frontend bundle gained Phase 3B learning UX, see
|
||
`docs/PHASE3B_LEARNING_AND_ASSESSMENT.md` §10–11). Start here, then go to the component you need:
|
||
|
||
- `provisioner/` — Postgres-backed environment registry and lifecycle. Design:
|
||
`docs/LAB_ARCHITECTURE.md`, `docs/PHASE1_PLATFORM_FOUNDATION.md`. Operational reference:
|
||
`provisioner/README.md`.
|
||
- `api/` — the lightweight Platform API: students, cohorts and cohort membership, curriculum,
|
||
detailed scenario attempt telemetry, progressive hints, curriculum completion rules, the exam +
|
||
capstone assessment engine, achievements, per-instructor accounts, persistent student/
|
||
instructor sessions, RBAC, audit logging, real student credentials + remote classrooms
|
||
(Phase 5A), self-paced programs/enrollment + the website integration boundary (Phase 5B), and
|
||
a provider-neutral enrollment-communications pipeline (activation/enrollment-confirmation/
|
||
password-reset email, Phase 5C), the ROOT_ course/module/activity content model layered over
|
||
curriculum/assessments (Phase 6A) with real teaching content across most of the Kubernetes
|
||
courses and a server-side capstone unlock enforcement fix (Phase 6B), and the instructor/admin
|
||
control plane. No k3s, no
|
||
`--privileged` — this replaced Phase 2A's "identity" instance, which was a full Lab image
|
||
booting an unused k3s cluster just to serve these APIs. Design:
|
||
`docs/PHASE2B_ADMIN_AND_PLATFORM_DATA.md` (split + Postgres migration),
|
||
`docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` (sessions, accounts, RBAC, audit),
|
||
`docs/PHASE3B_LEARNING_AND_ASSESSMENT.md` (learning/assessment engine),
|
||
`docs/PHASE5A_STUDENT_IDENTITY_REMOTE_CLASSROOM.md` (student credentials, remote classroom),
|
||
`docs/PHASE5B_SELF_PACED_ENROLLMENT.md` (programs, enrollment, website integration boundary),
|
||
`docs/PHASE5C_ENROLLMENT_COMMUNICATIONS.md` (notifications, email delivery),
|
||
`docs/PHASE6A_ROOT_COURSE_FOUNDATION.md` (course/module/activity content model, gold-standard
|
||
module), `docs/PHASE6B_ROOT_CURRICULUM_EXPANSION.md` (curriculum authoring across ROOT
|
||
05-10/12/Capstone, the capstone unlock fix). Operational reference: `api/README.md`.
|
||
- `gateway/` — the only student-facing path to a Lab (HTTP + WebSocket proxy, environment-aware
|
||
routing derived from a server-controlled session — not a client-suppliable header/param — and,
|
||
as of Phase 3B, server-side gating of progressive hint reveal). Design:
|
||
`docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md` (routing), `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md`
|
||
(persistent sessions, CSRF), `docs/PHASE3B_LEARNING_AND_ASSESSMENT.md` §3 (hint gating).
|
||
- `egress-proxy/` — shared allowlisting proxy every Lab's outbound traffic passes through.
|
||
- `lab-router/` — Phase 4.1 addition. Runs on the Lab Host VM (or `dev-local`'s stand-in in
|
||
local dev, though `direct` mode there never exercises it); resolves an opaque routing token
|
||
to a local Lab container purely from Docker state, over mTLS, so the Gateway never needs a
|
||
Docker-internal address. Design: `docs/PHASE4_1_PREPRODUCTION_HARDENING.md` §1-3.
|
||
- `docker-compose.dev.yml` — the full stack (Postgres, egress proxy, Provisioner, Platform API,
|
||
Gateway) on one machine. This is the Phase 1/2A/2B **local dev exception** — production is
|
||
the two-VM Proxmox split described in `docs/LAB_ARCHITECTURE.md` §1.
|
||
|
||
## Running the full stack locally
|
||
|
||
```bash
|
||
cd platform
|
||
echo "PROVISIONER_SHARED_SECRET=$(openssl rand -hex 32)" > .env
|
||
docker compose -f docker-compose.dev.yml build
|
||
docker compose -f docker-compose.dev.yml up -d
|
||
|
||
# First run only — create the owner account (no ADMIN_PASSWORD anymore, see
|
||
# docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md):
|
||
cd api
|
||
PLATFORM_DB_URL=postgres://postgres:postgres@localhost:5433/rootnode_platform \
|
||
node bootstrap-owner.js [email protected] "Your Name" "a-real-password-12-chars-plus"
|
||
```
|
||
|
||
No k3s boot to wait for at this layer anymore (Platform API starts instantly) — the whole
|
||
platform is reachable at `http://localhost:4200` (the Gateway) right away: students at `/`,
|
||
instructors at `/admin` (sign in with the owner account you just bootstrapped, then create
|
||
further instructor accounts from the Instructors tab).
|
||
|
||
## Tests
|
||
|
||
- `provisioner/test/run.js` — fast, isolated Provisioner tests (network/container/firewall
|
||
mechanics, no Gateway/Platform API involved). Run against `provisioner/docker-compose.dev.yml`.
|
||
- `test/e2e-phase2a.js` — student-flow regression through real session cookies: roster → login
|
||
→ curriculum → launch → Gateway routing → cross-student rejection → progress relay → reset.
|
||
- `test/e2e-phase2b.js` — the classroom acceptance workflow: instructor creates a cohort, adds
|
||
students, assigns curriculum, Prepare Labs (concurrent), students complete different
|
||
scenarios, instructor resets one, instructor destroys all cohort Labs after class — progress
|
||
survives every step.
|
||
- `test/e2e-phase3a.js` — persistent sessions (including a real Platform API restart), instructor
|
||
auth (no enumeration, rate limiting), RBAC across owner/admin/instructor, cohort-scoped
|
||
instructor access, CSRF enforcement, password change, and audit logging.
|
||
- `test/e2e-phase3b.js` — attempt telemetry, progressive hint sequencing/persistence through a
|
||
Lab reset, curriculum stage/Capstone lock-unlock, the exam engine (random draw, server
|
||
timer, expiry, restart persistence), the Capstone workflow end to end, two-student assessment
|
||
isolation, and instructor learning analytics/RBAC.
|
||
- `test/e2e-phase5a.js` — real student credentials (activation/password reset/login), remote
|
||
classroom sessions (join/heartbeat/announcements/help requests), and instructor conversion of
|
||
a pilot student to a credentialed account.
|
||
- `test/e2e-phase5b.js` — programs/enrollment, entitlement gating (pending/future/expired/
|
||
cancelled), server-derived completion, disposable-Lab persistence across destroy/recreate, and
|
||
the website/commerce integration boundary (idempotency, concurrency, RBAC).
|
||
- `test/e2e-phase5c.js` — the notification lifecycle (queue/retry/failure/exhaustion),
|
||
activation/enrollment-confirmation/password-reset email delivery via the deterministic dev
|
||
provider, minor/no-email contact-email resolution, and admin notification RBAC.
|
||
- `test/e2e-phase6a.js` — course/module/activity hierarchy and ordering, prerequisite-based
|
||
locking, all three completion behaviors (manual marker/scenario/assessment-derived), resume,
|
||
cross-student isolation, RBAC for self-paced (no-cohort) students, and draft-content hiding.
|
||
- `test/e2e-phase6b.js` — hierarchy for the 13 new modules across ROOT 05-10/12/Capstone,
|
||
prerequisite chains through the newly-inserted front-door modules, the optional-vs-required
|
||
(`is_required`) completion rule, and the capstone server-side unlock fix in both directions
|
||
(a direct bypass attempt rejected, a legitimately unlocked attempt still accepted).
|
||
- `test/e2e-phase6c.js` — curriculum completion upgrades, the security assessment bank, and
|
||
ROOT 11's honest lesson-only scope.
|
||
- `test/e2e-phase6d.js` — ROOT 01 (Computing & Linux Foundations) as the program's real front
|
||
door, and the real ROOT 01-04 foundational prerequisite chain.
|
||
- `test/e2e-phase6e.js` — ROOT 02/03/04 completion, the full ROOT 01->02->03->04->05 chain
|
||
proven via direct API, and the course/module lock-enforcement fix on the manual-completion
|
||
route.
|
||
- `test/e2e-phase6f.js` — the ROOT_ V1 curriculum manifest (inclusions/exclusions), the full V1
|
||
prerequisite graph (no cycles, no missing nodes), the strengthened Capstone gate (ROOT 09 AND
|
||
ROOT 12 both required) in both directions, the new orientation module, and an explicit check
|
||
that no age/grade gate exists anywhere in enrollment.
|
||
- `test/e2e-phase7.js` — organizations/locations, guardians and student-guardian relationships,
|
||
curriculum packages (reference-only, never a content clone), offerings (capacity, server-
|
||
defined status transitions), the registration lifecycle through agreement acceptance and
|
||
conversion to a real enrollment, registration/guardian RBAC, explicit age-guidance-is-never-
|
||
an-authorization-check verification, and confirmation that existing ROOT_ V1/self-paced/
|
||
classroom flows are unaffected.
|
||
- `test/e2e-phase8.js` — offering launch readiness, server-authoritative registration open/
|
||
closed enforcement, capacity concurrency through the real registration endpoints, the public
|
||
offering serializer (no internal/PII leakage), the website registration integration contract
|
||
(sequential and concurrent idempotency), required-agreement conversion blocking with version
|
||
snapshotting, guardian notification recipient resolution, and confirmation that ROOT_ V1/self-
|
||
paced/classroom flows remain unaffected.
|
||
- `test/e2e-phase9.js` — offering pricing in the public serializer, checkout blocked until
|
||
agreements are accepted, the server-authoritative amount (never caller-supplied), webhook
|
||
signature verification and idempotency, payment success driving real conversion/activation, a
|
||
failed payment leaving the seat intact vs. an abandoned checkout releasing it, the reservation
|
||
reaper, a last-seat checkout race, manual refund with no cascade into registration/enrollment
|
||
status, minor payment confirmations routing to the guardian, the admin payment view (never card
|
||
data), instructor/public RBAC on payment data, audit/metric hygiene (no secrets, no
|
||
high-cardinality labels), the website status-lookup endpoint's minimal safe shape, and
|
||
confirmation that ROOT_ V1/free-offering/classroom flows remain unaffected.
|
||
|
||
`infra/scripts/drills/` also holds real-Lab dress rehearsals per phase (Phase 6D/6E foundations,
|
||
Phase 6F's multi-student pilot and full end-to-end V1 journey, Phase 7/8's Winter Break Camp
|
||
rehearsals, Phase 9's Winter Break COMMERCE rehearsal —
|
||
`test-phase9-winter-camp-commerce.js`, 13/13, real checkout/webhook against the deterministic
|
||
test payment provider, no live money) — see each script's own header and
|
||
`docs/PHASE6F_ROOT_V1_PILOT_READINESS.md`/`docs/PHASE8_ENROLLMENT_OPERATIONS.md`/`docs/
|
||
PHASE9_COMMERCE_AND_LAUNCH.md` for what they prove beyond what the e2e suites above already
|
||
cover via direct API.
|
||
|
||
All e2e suites need `OWNER_EMAIL` / `OWNER_PASSWORD` set to a real bootstrapped instructor
|
||
account (see "Running the full stack locally" above) — the old `ADMIN_PASSWORD` mechanism is
|
||
gone. They're slow (real k3s boots, `e2e-phase3b.js` also runs a real API restart) and need the
|
||
full stack up. Run each suite against its own freshly-reset stack, not chained one after another
|
||
against the same Postgres — several routes (the admin dashboard's running-lab count, a course's
|
||
percent-complete) read GLOBAL state on purpose, and chaining suites produces false failures from
|
||
shared state, not real regressions (found and documented during Phase 6A's own regression pass).
|
||
None of them substitute for the manual real-Lab-image checks (node-pty, terminal
|
||
WebSocket, `kubectl`, scenario validation) in `docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md` §8 —
|
||
those need a browser-equivalent client and aren't automated here. Two exceptions get a real-Lab
|
||
dress rehearsal instead: Phase 6A's gold-standard module
|
||
(`infra/scripts/drills/run-phase6a-course-rehearsal.sh`) and Phase 6B's curriculum expansion,
|
||
including a real `kubectl expose` and a real instructor/classroom narrative
|
||
(`infra/scripts/drills/run-phase6b-root-course-rehearsal.sh`).
|
||
|
||
## Known limitations
|
||
|
||
See `provisioner/README.md` (Phase 1), `docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md` §9 (Phase
|
||
2A), `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` (Phase 3A identity limitations), and
|
||
`docs/PHASE3B_LEARNING_AND_ASSESSMENT.md` §20 (Phase 3B learning/assessment limitations) for the
|
||
full, honest lists. Phase 3B's "no automatic abandoned-attempt detection" and "no per-cohort
|
||
needs-attention threshold configuration" limitations were both closed in Phase 4.1 (§13/§17 of
|
||
`docs/PHASE4_1_PREPRODUCTION_HARDENING.md`); its raw-JSON pool_spec limitation was replaced with
|
||
a structured editor (§18) with an owner-only raw-JSON fallback still available. Phase 4.1's own
|
||
known limitation: real remote/self-paced delivery needs student email/password authentication,
|
||
not built — see `docs/REMOTE_AND_SELF_PACED_ARCHITECTURE.md`.
|
||
|
||
## Running this in production
|
||
|
||
`../infra/` has the full production infrastructure package (Ansible, Terraform, firewall,
|
||
monitoring, backup, CI/CD) for deploying the Platform API/Gateway/Provisioner/Postgres onto a
|
||
dedicated `rn-platform-01` VM, with student Labs — and a new `lab-router` service
|
||
(`../platform/lab-router/`) — on a separate `rn-lab-host-01` VM. See
|
||
`../docs/PHASE4_PRODUCTION_INFRASTRUCTURE.md` for the overview and
|
||
`../docs/PHASE4_1_PREPRODUCTION_HARDENING.md` for how Gateway-to-Lab reachability across two
|
||
real VMs was closed (a Lab Host Router + mTLS data plane, simulation-tested in
|
||
`../infra/scripts/simulate-two-host/`) and for the rest of Phase 4.1's pre-production hardening.
|