Skip to content

English · Español

Theory 00 — Why a portal at all

🇪🇸 El currículum pre-escrito (A12) es un libro de texto: completo, ordenado, navegable. Pero un libro no aprende contigo. El portal cierra ese hueco: identifica al estudiante, registra qué leyó y qué falló, y le devuelve sus fallos en el momento espaciado correcto. Es la pieza que convierte el currículum en tutoría.

The question this file answers

If LYNX_CORTEX_ADDENDUM.md §A12 already pre-writes 40 phases of theory + lab statements + plans, what does a web portal add that a directory of Markdown does not?

The honest answer is: nothing, for the first learner. Borja can study the repo with mkdocs serve and a text editor. The portal earns its keep only when (a) more than one person is studying the curriculum, (b) the same person studies across many sessions and needs the system to remember their state, and © failure is a signal we want to act on automatically — re-presenting wrong answers at the right time, not just logging them.

This file establishes those three claims as the only justification for the portal's existence, and lets every design decision downstream flow from them. If a feature does not serve (a), (b), or ©, it is out of scope.

The contract between the curriculum and the learner

The pre-written curriculum makes a contract:

"At any phase NN, the theory you need to understand the lab is committed; the lab states the problem precisely; the solution is held back until you have committed an attempt."

The contract is stateless with respect to the learner. The repo does not know who is reading it. It does not know which lab they have attempted. It does not know which exam questions they failed three weeks ago.

For a single learner working in one long sitting, this is fine — the learner is the state. For:

  • A second learner joining six months later: the curriculum is intact, but their progress is invisible to anyone else.
  • The same learner returning after a 10-day pause: nothing in the repo tells them where they were, what was hard, or what they still owe.
  • A teacher who wants to see how three students are doing: there is no view.

The portal is the state-keeping layer over the stateless curriculum. The curriculum stays as it is — markdown files in docs/, source modules in src/. The portal renders it, attributes each student's interactions with it, and closes the loop on failures.

A key consequence: the portal must never own curriculum content. If a phase's theory file lives in the database, the database becomes a second source of truth and we have a migration problem on every commit. Theory and lab statements stay in docs/; the portal reads them at request time and renders them through Jinja2. The DB owns only learner state: students, sessions, notes, quiz attempts, exam attempts, review cards, events. Nothing else.

Why pre-writing is not enough

A12 pre-writes the materials. It does not pre-write the mentoring loop. The mentoring loop has three properties no static document can have:

  1. Identity. Two people can read the same theory file; the portal knows which person read it and when, so we can answer "did Ana get past Phase 17?" without asking Ana.
  2. Memory of failure. When a student answers an exam question incorrectly, the portal records it in a way that lets it be re-presented later. The static curriculum can show you the right answer once; it cannot keep coming back to you, three days later, then nine, then twenty, until the wrong answer becomes the right one. This is spaced repetition (theory 01 §SR), and it is the single most important thing the portal adds.
  3. Process visibility. A note that says "this confused me on day 4" is invisible unless the system stores it where the teacher (or future-self) can read it. The portal makes "stuck-ness" addressable.

Without these three properties, pre-writing the curriculum is a one-way broadcast. With them, the curriculum becomes a correspondence — call-and-response across days and weeks.

The no-password-by-default decision

Most portals ship with a default admin password (admin/admin, or one printed in the install script). Industry-wide, this is the single most common vector for compromised dev / staging deployments — including in repositories that teach security (the irony does not save them). security/THREATS.md from Phase 37 explicitly flags this class of misconfiguration.

Phase 41's stance is sharper:

No password is ever generated, defaulted, transmitted, or stored "temporarily." The only way a student's password enters the system is when the student types it on first login.

Mechanically: the admin issues a one-time invite token — a short URL-safe string signed with itsdangerous, including the student id, an issue timestamp, and a single-use nonce. The student opens the link, sees a form with two password fields, picks their password, submits. The portal:

  1. Verifies the token's signature, timestamp (within TTL, default 24 hours), and that the nonce has not been used.
  2. Hashes the chosen password with Argon2id + the server pepper.
  3. Stores the hash; invalidates the token.
  4. Issues a session cookie. The student is in.

The admin never sees the password. The repo never stores a default password. The invite link is the only artifact in the threat model that has the property "redeems to credentials," and it has a TTL and a single-use property.

This ergonomic decision falls out cleanly from the threat-model work of Phase 37 and is the only mechanism the portal supports for adding a student. Lab 01 walks the flow.

The multi-student axis

There are three roles in the portal:

  • Student. Default role. Can see only their own state. Can read curriculum (open to everyone). Can submit notes, quizzes, exams. Can see their own review deck.
  • Teacher. Sub-case of admin (in v1 the two are merged; the BLUEPRINT separates them for a future split). Can see all students' progress, notes, and exam history. Cannot impersonate a student. Reads are audited (theory 01 §audit).
  • Admin. Creates students. Issues invite links. Rotates the server pepper. Cannot read individual quiz answers — that is a teacher concern, not an infrastructure one.

Why this split matters: combining "creates accounts" with "reads notes" produces a god-role, which is bad both for least-privilege (security/THREATS.md) and for the social dynamics of a small cohort. In v1 the same human (Borja, then later anyone running the repo) wears both hats — but the system logs each action against the role exercised, so the audit trail is honest.

Specifically: every admin or teacher read of a student's notes writes an event_log row tagged admin_read_notes with the student id, the admin id, and a timestamp. The student can see who read their notes and when, via their own dashboard. This is not surveillance defense — it is mutual visibility: if I can see your notes, you can see that I looked.

The mentoring loop, concretely

For each exam question:

  • The portal stores the question, the canonical answer, the rubric (string match / multiple choice / numeric ± tolerance).
  • When a student answers, the portal scores it.
  • If wrong: the question enters the student's review deck with an SM-2 schedule. The first re-presentation is the next day; subsequent re-presentations stretch by the ease-factor multiplier; failures reset the interval.
  • If right after previously being wrong: the question's interval extends and it stays in the deck (still re-presentable; the curriculum cares more about retention than first-pass scoring).
  • If right after enough consecutive correct re-presentations (default: 3 at intervals ≥ 21 days): the question retires.

The mathematical core (SM-2 update rule + ease factor formula) is in PHASE_41_PLAN.md §2 and developed in lab 04. The pedagogical point is in this file: the portal exists to make the loop, not the score, the deliverable. A wrong answer is the start, not the end, of learning.

What process logging is for

The event_log table is the queryable form of the §A4 three-layer log's middle layer (daily journal), promoted to a row per event. It enables:

  • "Did this student actually open phase 13's theory file before attempting the lab?" (auditing curriculum compliance.)
  • "How long between opening the lab and submitting the exam?" (time-on-task estimate.)
  • "Which phase do students most often abandon?" (a curriculum-quality signal.)
  • "What is the gap between a failed exam question and its first correct re-presentation?" (a learning-velocity signal.)

It is not for:

  • Replacing the journal. The journal is reflective prose; the event log is structured events. Both are kept.
  • Surveilling individual sessions. The granularity is per-action, not per-keystroke.

Lab 03 builds the event-log queries and the admin dashboard.

The Spanish thread

A2 (bilingual policy) and A13 (grammar-tutor scope) both demand Spanish presence. The portal honors both:

  • A13 (subject matter): every exam question presented to a student is in English with a paired Spanish translation in the question stem, exactly as the corpus stores them. The mentor loop is bilingual by construction.
  • A2 (canonical English with Spanish summaries): templates display canonical English content; an optional "🇪🇸 Resumen" partial renders the inline Spanish summaries that the theory files already contain. Toggleable per student in their preferences.

The portal does not translate dynamically. It surfaces the translations the curriculum already committed.

What this file does NOT cover

  • The architecture (FastAPI, SQLite, Jinja2, HTMX, Argon2id) is in theory/01-architecture.md.
  • The math of SM-2 is in PHASE_41_PLAN.md §2 and lab 04.
  • The security replay of Phase 37 threats is in lab 05.
  • Why HTMX over React is in theory/01-architecture.md (a paragraph defending the choice against §10 of the spec).
  • Email delivery, SSO, payments are out of scope per PHASE_41_PLAN.md §8 — and they would be three separate amendments if they ever land.

A meta-lesson

The portal is the smallest piece of infrastructure that makes the curriculum genuinely multi-tenant and mentoring-capable. It is intentionally not impressive. It does not have a JavaScript framework, a worker pool, a message queue, a Kubernetes manifest, a metrics-and-traces stack, or a multi-cloud story. The grammar tutor (Phase 39) has all of those; the portal has none of them, because the portal is delivery, not inference.

A common failure mode in education tools is to over-build the delivery layer until it eclipses the curriculum. Phase 41's design pressure goes the other way: every feature that does not serve identity, memory-of-failure, or process-visibility is rejected. The portal is small on purpose.

Next: 01-architecture.md — the C4 walk-through, the FastAPI + Jinja2 + HTMX stack, the canonical "submit exam answer" request flow with Phase 37 middleware applied.