docs(phase2b): document admin and platform-data architecture
New docs/PHASE2B_ADMIN_AND_PLATFORM_DATA.md covers the Platform API split, Postgres schema and migration guarantees/rollback, the session cookie architecture (including the whoami-routing-bug fix), the admin portal, the API/security boundary, known limitations, and Phase 3+ future work. Updates ENGINEERING_SOP.md §8, LAB_ARCHITECTURE.md, README.md, and platform/README.md to reflect Platform API as the sole Provisioner caller and Postgres as authoritative for identity/progress as of Phase 2B.
This commit is contained in:
@@ -134,11 +134,18 @@ layers rather than changing the image itself:
|
||||
|
||||
- `platform/provisioner/` — Postgres-backed environment registry, per-student Docker
|
||||
networking, firewall-enforced egress, idle reaper (`docs/PHASE1_PLATFORM_FOUNDATION.md`).
|
||||
- `platform/gateway/` — the only student-facing path to a Lab: resolves identity → environment
|
||||
→ routing token, proxies HTTP/WebSocket into that one student's container, never a raw
|
||||
container IP/port (`docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md`).
|
||||
- `platform/api/` — lightweight Platform API: students, cohorts, curriculum, progress,
|
||||
scenario attempts, student/admin sessions, instructor/admin control plane. No k3s, no
|
||||
`--privileged` (`docs/PHASE2B_ADMIN_AND_PLATFORM_DATA.md`).
|
||||
- `platform/gateway/` — the only student-facing path to a Lab: resolves identity from a
|
||||
server-controlled session cookie (not a client-suppliable header/param), proxies
|
||||
HTTP/WebSocket into that one student's container, never a raw container IP/port
|
||||
(`docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md`, session model in
|
||||
`docs/PHASE2B_ADMIN_AND_PLATFORM_DATA.md` §3).
|
||||
- The student flow (roster login → curriculum dashboard → Launch Lab → Lab session →
|
||||
Reset/Recreate) lives in `frontend/src/platform/` — a small addition alongside the existing,
|
||||
Reset/Recreate) lives in `frontend/src/platform/`; the instructor/admin portal
|
||||
(cohorts, students, classroom "Prepare Labs," environment controls) lives in
|
||||
`frontend/src/admin/` at the `/admin` route — both small additions alongside the existing,
|
||||
unmodified Lab UI, not a rewrite of it.
|
||||
|
||||
**Never publish the raw privileged container** — front it with isolation (that's what the
|
||||
@@ -151,9 +158,14 @@ Key properties of the platform (not this image):
|
||||
- One container **per student**, its own Docker network, its own firewall chain — never a
|
||||
shared cluster between learners. Verified with two simultaneous students: separate clusters,
|
||||
separate progress, no cross-access.
|
||||
- Progress/identity live outside the disposable container (a persistent identity instance
|
||||
running this same image, currently SQLite-backed, moving to the Platform's PostgreSQL in a
|
||||
later phase) — destroying or recreating a student's Lab never loses their academic record.
|
||||
- Progress/identity live outside the disposable container, in the Platform API's own
|
||||
PostgreSQL (authoritative as of Phase 2B) — destroying or recreating a student's Lab never
|
||||
loses their academic record. Verified with a full class-sized (3-student) cohort workflow:
|
||||
provision, complete different scenarios, reset one student's Lab, destroy all Labs after
|
||||
class — progress survives every step.
|
||||
- Instructors manage cohorts, students, curriculum assignment, and classroom Lab prep
|
||||
(provision an entire cohort before class, verify readiness, destroy Labs after) from
|
||||
`/admin` — no manual database, Docker, or Kubernetes access needed.
|
||||
- CPU/memory/PID/storage limits are enforced per container, config-driven.
|
||||
- Egress is restricted to an allowlisted proxy at the firewall layer, not left open.
|
||||
- Idle/abandoned environments are automatically cleaned up, and a student can launch a fresh
|
||||
|
||||
Reference in New Issue
Block a user