docs(phase3b): document the learning and assessment engine
New docs/PHASE3B_LEARNING_AND_ASSESSMENT.md covers the attempt/learning-record model, progressive hints (including the Gateway response-rewrite mechanism), curriculum completion rules, the assessment/exam engine and its timer/draw integrity guarantees, the RootNode Capstone design, achievement records, the deliberately minimal versioning model, instructor analytics, the Phase 3B RBAC matrix, security/integrity assumptions, dev/test commands, known limitations, and the Phase 4 boundary. Updates ENGINEERING_SOP.md (roadmap items 2/7/8 now done, new section 12, corrects a stale capstone-placeholder description in section 4), LAB_ARCHITECTURE.md's status line, README.md (corrects the 'Lab image unmodified' claim now that its frontend bundle carries Phase 3B UX, plus new platform properties), platform/README.md, and platform/api/README.md.
This commit is contained in:
+29
-18
@@ -1,21 +1,27 @@
|
||||
# RootNode Academy — Platform
|
||||
|
||||
The full multi-student platform, layered on top of the unmodified Lab image at the repo root.
|
||||
Start here, then go to the component you need:
|
||||
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, enrollments, curriculum, progress,
|
||||
scenario attempts, per-instructor accounts, persistent student/instructor sessions, RBAC,
|
||||
audit logging, 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). Operational reference: `api/README.md`.
|
||||
- `api/` — the lightweight Platform API: students, cohorts, enrollments, 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, 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). 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).
|
||||
Design: `docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md` (routing), `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` (persistent sessions, CSRF).
|
||||
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.
|
||||
- `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
|
||||
@@ -54,16 +60,21 @@ further instructor accounts from the Instructors tab).
|
||||
- `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.
|
||||
|
||||
All three e2e suites need `OWNER_EMAIL` / `OWNER_PASSWORD` set to a real bootstrapped instructor
|
||||
All four 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) and need the full stack up. 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.
|
||||
gone. They're slow (real k3s boots, `e2e-phase3b.js` also runs a real API restart) and need the
|
||||
full stack up. 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.
|
||||
|
||||
## Known limitations
|
||||
|
||||
See `provisioner/README.md` (Phase 1), `docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md` §9 (Phase
|
||||
2A), and `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` (Phase 3A, supersedes Phase 2B's
|
||||
identity limitations) for the full, honest lists.
|
||||
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.
|
||||
|
||||
+17
-11
@@ -1,9 +1,11 @@
|
||||
# RootNode Academy — Platform API (Phase 3A)
|
||||
# RootNode Academy — Platform API (Phase 3B)
|
||||
|
||||
Lightweight service: no k3s, no `--privileged`, no Lab terminal runtime. See
|
||||
`docs/PHASE2B_ADMIN_AND_PLATFORM_DATA.md` for the original split/migration design and
|
||||
`docs/PHASE2B_ADMIN_AND_PLATFORM_DATA.md` for the original split/migration design,
|
||||
`docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` for persistent sessions, per-instructor
|
||||
accounts, RBAC, and audit logging — this file is the operational reference.
|
||||
accounts, RBAC, and audit logging, and `docs/PHASE3B_LEARNING_AND_ASSESSMENT.md` for attempt
|
||||
telemetry, progressive hints, curriculum rules, and the exam/capstone engine — this file is the
|
||||
operational reference.
|
||||
|
||||
## Configuration reference
|
||||
|
||||
@@ -71,14 +73,18 @@ with instructor accounts, which are Phase 3A-native and start empty until you bo
|
||||
## Tests
|
||||
|
||||
`platform/test/e2e-phase2a.js` (student-flow regression), `platform/test/e2e-phase2b.js` (the
|
||||
classroom acceptance workflow), and `platform/test/e2e-phase3a.js` (persistent sessions
|
||||
including a real restart, instructor auth, RBAC, cohort scoping, CSRF, audit log). All three
|
||||
need the full stack up and `OWNER_EMAIL` / `OWNER_PASSWORD` set to a bootstrapped account — see
|
||||
`platform/README.md`.
|
||||
classroom acceptance workflow), `platform/test/e2e-phase3a.js` (persistent sessions including a
|
||||
real restart, instructor auth, RBAC, cohort scoping, CSRF, audit log), and
|
||||
`platform/test/e2e-phase3b.js` (attempt telemetry, progressive hints, curriculum/Capstone
|
||||
unlock rules, the exam engine including a real restart, two-student assessment isolation,
|
||||
instructor analytics). All four need the full stack up and `OWNER_EMAIL` / `OWNER_PASSWORD` set
|
||||
to a bootstrapped account — see `platform/README.md`.
|
||||
|
||||
## Known limitations
|
||||
|
||||
See `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` "Known limitations" — sessions are
|
||||
Postgres-backed (survive a restart) but there's no distributed revocation channel to the
|
||||
Gateway's short-lived whoami cache, exam mode's live bookkeeping stays Lab-local, and OIDC/SSO
|
||||
is a documented adapter interface, not a working integration yet.
|
||||
See `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` "Known limitations" (sessions are
|
||||
Postgres-backed and survive a restart, but there's no distributed revocation channel to the
|
||||
Gateway's short-lived whoami cache; OIDC/SSO is a documented adapter interface, not a working
|
||||
integration yet) and `docs/PHASE3B_LEARNING_AND_ASSESSMENT.md` §20 (no automatic
|
||||
abandoned-attempt detection, needs-attention thresholds are fixed constants, `pool_spec`
|
||||
authoring is raw JSON in the admin UI).
|
||||
|
||||
Reference in New Issue
Block a user