Skip to content

English · Español

Phase 41 — Learner Portal: Delivering the Curriculum to Many

Requires: 40 — Hardening, Postmortem, "What's Next" Teaches: web-portal · argon2id · csrf · spaced-repetition · multi-tenancy Jump to any chapter from the phase reference index.

Chapter map

🇪🇸 La fase 41 no añade conocimiento de IA: añade acceso. Un único proceso FastAPI sirve el currículum de 40 fases a varios estudiantes, con login (sin contraseña por defecto), vista de profesor / admin, registro de proceso por estudiante, y repetición espaciada de preguntas de examen falladas. La construcción real espera a las fases 33 (serving) y 37 (seguridad). Esto es el portal — no el tutor.

Where this phase lives in the curriculum

  • Spec anchor: LYNX_CORTEX.md §3 (audience: future cohorts) + §4 / Phase 33 (FastAPI) + §4 / Phase 37 (security / threat model).
  • Amendment anchor: LYNX_CORTEX_ADDENDUM.md §A14 — Phase 41 is a post-curriculum phase added after the original 40-phase scope and is governed by A14 (drafted alongside this README).
  • Topic anchor: §A13 — the subject matter the portal delivers is the grammar-tutor curriculum (20 verbs × 5 tenses × 3 persons with paired Spanish translations). The portal itself has no model.
  • Method anchor: §A12 — this phase is pre-written: plan + theory + lab statements before phase open; solutions just-in-time.
  • Prerequisites: Phases 33 and 37 must be closed first.
  • Plan: PHASE_41_PLAN.md at repo root.

What the portal produces

A single command — just portal — starts a FastAPI process on localhost:8000 that does the following:

  1. Authenticates students via Argon2id-hashed credentials backed by the src/minivault/ module. No default password is ever set or transmitted; the admin issues a one-time invite link, the student redeems it and sets their own password.
  2. Renders the curriculum phase-by-phase from docs/phase-NN-*/. Theory and lab statements are pulled live from the repo; the database owns only learner state, never curriculum content.
  3. Captures process via an event_log table: who read what, when, against which artifact SHA. The teacher / admin can inspect any student's chronological trail.
  4. Quizzes and exams drawn from each phase's question bank (subject matter: grammar-tutor §A13). Free-form notes stored alongside.
  5. Re-presents failures through src/minireview/: failed exam questions enter the student's review deck, scheduled by SM-2, drained one at a time until correctly answered.
  6. Administers via a teacher / admin role that can: create new students, inspect progress, audit notes, and see the review-deck health per student.

Plus, committed to the repo:

  • src/miniportal/BLUEPRINT.md — FastAPI app design, route map, template inventory.
  • src/minivault/BLUEPRINT.md — Argon2id config, pepper handling, verification API.
  • src/minireview/BLUEPRINT.md — SM-2 (and feature-flagged FSRS) scheduler design.
  • docs/phase-41-learner-portal/theory/ — motivation + architecture.
  • docs/phase-41-learner-portal/lab/ — six lab statements (00 → 05).
  • infra/portal/Caddyfile.example — recommended reverse-proxy config (cited; not bundled into just portal).
  • PHASE_41_REPORT.md — phase reflection at close.

Hands-off file map

Path Owner Status
PHASE_41_PLAN.md Claude (pre-write) → Borja (revisions) Pre-written
docs/phase-41-learner-portal/README.md Claude (pre-write) Pre-written (this file)
docs/phase-41-learner-portal/theory/00-motivation.md Claude (pre-write) Pre-written
docs/phase-41-learner-portal/theory/01-architecture.md Claude (pre-write) Pre-written
docs/phase-41-learner-portal/lab/0[0-5]-*.md Claude (pre-write of statements; no solutions) Pre-written separately
docs/phase-41-learner-portal/solutions/*.md Claude (just-in-time, after Borja's attempt) ⏳
src/miniportal/BLUEPRINT.md Claude (scaffold) → Borja (amend) ⏳
src/minivault/BLUEPRINT.md Claude (scaffold) → Borja (amend) ⏳
src/minireview/BLUEPRINT.md Claude (scaffold) → Borja (amend) ⏳
src/miniportal/*.py, src/minivault/*.py, src/minireview/*.py Borja only (CLAUDE.md §0.2) ⏳
PHASE_41_REPORT.md Borja (at phase close) ⏳

Theory chain (read in order)

  1. theory/00-motivation.md — why a portal exists at all; the curriculum / mentoring split; why pre-writing is not enough; the passwordless-first-login choice; the multi-student / teacher-admin axis; ethics of process logging.
  2. theory/01-architecture.md — C4 context + container diagrams; FastAPI + Jinja2 + HTMX + SQLite + Argon2id stack; route inventory; the canonical "submit exam answer" sequence with Phase 37 middleware applied.

Lab chain (do in order, after Phases 33 + 37 close)

  1. lab/00-bring-up-and-first-student.md — bootstrap, admin creation, first student.
  2. lab/01-passwordless-first-login.md — invite token issue, redemption, revocation, expiry.
  3. lab/02-vault-and-sessions.md — Argon2id timing curve; signed-cookie session round-trip; logout & pepper rotation.
  4. lab/03-progress-and-events.md — process-log queries; admin dashboard build.
  5. lab/04-spaced-repetition.md — seed exam failures; advance the clock; verify SM-2 schedule; drain the deck.
  6. lab/05-security-replay.md — re-run Phase 37's three demo threats through the portal.

Definition of Done (binary, per docs/DONE_ENOUGH.md style)

Stated in full in PHASE_41_PLAN.md (at repo root) §7. Nine checks, all binary, all automated:

  • just portal boots in < 2 s; /health returns 200.
  • just portal-admin --create-admin <name> issues a one-time invite link; redeemed link sets the password; link is revoked.
  • A second admin-created student can log in, view phase 01, submit a note, take the quiz, take the exam.
  • A failed exam question appears in the student's review queue at the SM-2-scheduled time.
  • The admin progress view shows last-active, exam pass rate, and review-deck size per student.
  • experiments/41-security-replay/ confirms Phase 37's three demo threats are caught.
  • pytest src/miniportal/ src/minivault/ src/minireview/ is green.
  • bandit -r src/miniportal src/minivault src/minireview reports 0 high-severity findings.
  • PHASE_41_REPORT.md is committed per LYNX_CORTEX.md §7.6.

What this phase does NOT cover

  • No new ML technique. Phase 41 has no model and no training.
  • No SPA. Anti-goal §10 of the spec. HTMX + Jinja2 only.
  • No multi-cohort isolation. One SQLite file = one cohort.
  • No SSO / OAuth. Local credentials only.
  • No email delivery in v1. Invite links printed to the admin terminal.
  • No auto-grading of free-form notes. Notes are stored, not scored.
  • No "polish" refactors of earlier phases. If a Phase 33 or 37 contract needs to change to satisfy the portal, log it as a Phase 33/37 revision per A12's flexibility clause — do not silently patch it from Phase 41.

What to do when you finish

Write PHASE_41_REPORT.md per LYNX_CORTEX.md §7.6. Specifically: per-lab outcomes, the empirical Argon2id timing curve, the review-deck sizing observed under the seeded student, and the carry-overs (likely: email delivery, SSO, cohort isolation, FSRS migration).

Next: theory/00-motivation.md.

Further reading

Optional — enrichment, not required to pass the phase.