# Classroom User Journeys — Connected End-to-End Flows

**Status:** Working document — design review required before implementation
**Date:** 2026-04-16
**Purpose:** Map the complete user journeys through the federated classroom. Every journey shows: what the user does, what the system does, which agents orchestrate, which RAG state is active, what federation operations fire, and where install/upgrade touchpoints exist.

**Context:** prd-classroom.md §5.8 specifies 11 workflows (WF-1..WF-11). This document connects them into four personas' end-to-end paths. Gaps identified here feed implementation tasks.

**Cross-references:** prd-classroom.md, prd-federation.md §17, ADR-022/023, spec-classification-boundary.md, project_auth_tier_staging, project_prague_deployment_requirements.

---

## Journey 1: Student (UT, USA national, Austin-based)

### Phase map

| Phase | Duration | User action | System / Agent | RAG state | Federation state | Install |
|-------|----------|-------------|----------------|-----------|------------------|---------|
| **Enrollment** | Day 0 | Receives email with enrollment URL + token | WF-1: AXI provisions Open WebUI account; PRESS generates syllabus | Course corpus loaded into classroom RAG | Membership record created (TTL = course end); `classroom-default` trust profile applied | None (web-only MVP) |
| **Onboarding** | Day 1–2 | Opens URL; completes checklist (interview, consent, baseline quiz) | WF-2: AXI guides through onboarding toolkit; structured Q&A engine for interview | Course RAG active; community RAG read-only | Membership transitions PROBATION → ACTIVE on checklist completion | None |
| **Active learning** | Weeks 1–4 | Chats, runs `/research` loops, completes homework, attends lectures | AXI (chat); CURIO (research loops); SCAN (signal monitoring, cadence 30s active / 10min idle) | Course + community RAG; research findings accumulate in student-scoped corpus; GREEN findings auto-promote to classroom-shared | SCAN always-on cadence; CURIO loops federate findings within cohort (Mode 1) | Mid-semester: if version skew detected on Rascal, instructor gets `axi update` notification; students unaffected (web-only) |
| **Assessments** | Weeks 2, 3, 4 | Takes pre/mid/post quizzes; submits work | WF-3 (quiz); WF-10 (submission + grading); WF-4 (scoring) | Quiz mode: RAG disabled; grading mode: RAG re-enabled for rubric assistance | Assessment records stored under membership | None |
| **Check-ins** | Weekly | Responds to AXI's check-in Q&A | WF-5: AXI + SCAN; signal-triggered if `student_stuck` or `low_engagement` | SCAN reads student interaction history from signal RAG | None (intra-node) | None |
| **Presentations** | Week 4 | Presents research to cohort | WF-11: PRESS publishes; CURIO evaluates; peer feedback via chat | High-quality presentations indexed into course RAG (instructor-approved) | Presentation artifacts propagate to classroom federation members | None |
| **Completion** | End of course | Takes post-quiz; completes end-of-course interview | WF-9 (course review); course-review instruments submitted | Final RAG state frozen | Membership enters `RENEWAL_DUE`; if no renewal, expires to `EXPIRED` on TTL | None |
| **Archive** | +90 days | (Passive) | AXI triggers archive; harvest bundles generated per §5.9.5 | Student harvest bundle: research loops, sessions, findings, citations | Membership expired; classroom federation sealed | None |
| **Alumni** | Ongoing | Loads harvest bundle into next Axiom node or future course | New course's CURIO references prior harvest as background knowledge | Prior-course findings available as read-only reference corpus | Alumni longitudinal identity (prd-alumni.md) — prior membership is historical record; new course = new membership | If alumni returns: `axi install` (CLI) or web re-enrollment; prior harvest auto-loads |

### Key touchpoints by system

| System | When | What student sees |
|--------|------|-------------------|
| **Email** | Enrollment | URL + token + pre-reading |
| **Open WebUI (browser)** | All active phases | Chat, research loops, assessments, presentations |
| **Canvas (LMS)** | Passive | Official grades synced from Axiom |
| **Harvest bundle** (.axiompack) | Archive | Downloadable package of all authored content |
| **Next Axiom instance** | Alumni return | Harvest bundle loads as reference for new CURIO |

---

## Journey 2: Instructor (Ben or designated instructor)

### Phase map

| Phase | Duration | User action | System / Agent | RAG state | Federation state | Install |
|-------|----------|-------------|----------------|-----------|------------------|---------|
| **Course creation** | Pre-semester | Defines Course manifest (objectives, corpus, assessments, questionnaires); `axi course create --manifest course.yaml` | AXI scaffolds; PRESS validates manifest | Instructor curates course corpus; domain packs loaded | Federation spec template created (topology, lifecycle, domain classification) | `axi` installed on instructor laptop + Rascal (both on v0.10.10+); `axi install-shim` for SSH runner |
| **Classroom instantiation** | 2 weeks before | `axi classroom create --course <id> --students students.yaml`; students.yaml includes `{name, email, student_id, nationality}` | WF-1: AXI provisions accounts; nationality attestations signed; trust profile `classroom-default` applied | Course corpus snapshot published as `.axiompack` | Ephemeral federation created (ADR-023 lifecycle=ephemeral, expires_at=course-end-date); instructor node = federation root (single-key per ADR-024 Phase 1) | Prague node provisioned (if multi-site); federation manifest pushed to Prague |
| **Prague node setup** (if multi-site) | 1 week before | Provisions EU VM; `axi install && axi federation join <invite-token>` on Prague node | TIDY provisions infrastructure; federation identity binding; corpus replication starts | Rascal corpus → Prague via delta sync (60s cadence) | Prague node joins classroom federation as `relationship=cluster`; manifest accepted | EU node: fresh install from PyPI; `axi install-shim`; federation join ceremony |
| **Monitoring** | Throughout | Reviews dashboard; checks SCAN alerts; approves promotions; grades work | WF-4 (scoring); WF-5 (check-ins); AXI presents cohort status; SCAN signals surfaced with Bonsai narration | Instructor sees all student RAG queries + retrieval quality; CURIO proposals for corpus improvements | Instructor reviews federation health; trust profile adjustable mid-course | Canary: instructor can test a new `axi` release on their own node before pushing to classroom via security directive (ADR-024 §6) |
| **Mid-course adjustment** | Weeks 2–3 | Adds/modifies corpus, adjusts objectives, updates trust profile slider | Course manifest version bump; `.axiompack` delta pushed to all nodes | Corpus delta propagates within one sync cycle | Manifest update signed by instructor (federation root); version bump sequence-numbered | None (web students unaffected by backend updates) |
| **End-of-course** | Final week | Triggers end-of-course instruments; reviews data; `axi classroom complete <id>` | WF-9 (course review); harvest bundle generation; Canvas grade export | Final RAG state sealed; promotion candidates flagged for org-level review | Classroom federation transitions `active → completing → completed` | None |
| **Post-course analysis** | +90 days | Exports research data; writes paper; reviews cohort patterns | CURIO assists paper drafting; research export (§5.10); LangFuse analytics | Archived: read-only | Federation sealed; manifest archived | None |
| **Course template refinement** | Next semester prep | Reviews what worked; applies cross-cohort patterns; updates Course manifest | CURIO proposes improvements from cascade (§5.11.8); instructor reviews | Best findings promoted to Course Template RAG | Prior classroom's federation metadata informs next instantiation | None |

### Instructor-specific decision points

| Decision | When | Bonsai narration | Deterministic gate |
|----------|------|-------------------|--------------------|
| Approve student enrollment | Day 0 | "Student X has nationality Y; course includes EC modules Z" | Nationality gate per §5.11.4 |
| Approve knowledge promotion | Ongoing | "CURIO proposes: finding F validated by 3 students, confidence 0.92" | Trust profile slider → auto-approve-with-audit or prompt |
| Quarantine student | If incident | "Student X's session shows anomalous patterns [evidence]; quarantine preserves their work" | `axi classroom quarantine-student` signed by instructor |
| Approve canary release | If upgrade available | "New release v0.11.X: [changelog]; 3 federation_lifecycle scenarios passing; recommend testing on your node first" | `emergency_upgrade_policy: notify` by default |

---

## Journey 3: EU Student (non-UT, Czech national, Prague-based)

### Differences from Journey 1

Everything in Journey 1 applies PLUS:

| Concern | How it's handled | Reference |
|---------|------------------|-----------|
| **Nationality attestation** | Instructor signs `nationality: CZ` in students.yaml at enrollment. Per-access EC gate checks nationality on every content retrieval. | §5.11.4, spec-classification-boundary §S7 |
| **Export-controlled modules** | Student sees non-EC course content normally. EC-gated modules: student gets a clear message ("this module requires US authorization; available modules are [list]"). Bonsai narrates: "Some course modules cover export-controlled technology; as a non-US national you'll access the non-restricted modules. Your learning experience is designed to be complete without them." | §5.11.4, §5.11.6 |
| **Node preference** | Student's browser connects via Cloudflare Tunnel; CF geo-routes to Prague node for latency. Transparent to student. | project_prague_deployment_requirements |
| **Data residency** | If GDPR requires EU storage: Prague node stores EU student's interaction logs, session data, assessment responses locally. Aggregated analytics (no PII) sync to Rascal. | project_prague_deployment_requirements |
| **Corpus access** | Same course corpus as Austin students (replicated to Prague node). Community corpus accessible per public tier. EC corpus: access deterministically refused for CZ-national students. | prd-federation §8.6, spec-classification-boundary §S6 |
| **Research findings** | EU student's CURIO findings promote to classroom-shared corpus on Prague node → sync to Rascal within 60s. If finding references EC-gated content, the finding itself is tagged EC and follows the same nationality gate on return. | project_prague_deployment_requirements §5 |
| **Harvest bundle** | Same format as US student. EC-gated content the student never accessed is not in their bundle (they never authored it). Bundle is complete for what they DID access. | §5.9.5 |
| **LangFuse** | Traces from Prague node flow to Rascal's LangFuse over the tunnel (async, not user-facing latency). Instructor sees unified analytics across both sites. | project_prague_deployment_requirements §LangFuse |

### EU student onboarding flow (augmented WF-2)

1. Student receives enrollment email (same as Journey 1).
2. Opens URL — CF routes to Prague node.
3. Completes GDPR consent flow (additional step: "Your interaction data will be stored on the Prague server; anonymized analytics may be shared with the Austin node for research purposes. [Accept / Decline]").
4. Completes onboarding checklist (same as Journey 1).
5. During onboarding chat: Bonsai surfaces a note: "Some modules in this course cover regulated technology. You'll have full access to [N of M] modules. Your instructor has more details."
6. Onboarding proceeds normally.

---

## Journey 4: Returning Alumni

### Phase map

| Phase | When | User action | System | RAG state | Federation state |
|-------|------|-------------|--------|-----------|------------------|
| **Harvest received** | End of prior course | Downloads `.axiompack` (or it's auto-stored on their node if they had CLI installed) | Archive process per §5.9.5 | Harvest bundle: portable, self-contained | Prior classroom federation expired; alumni identity persists |
| **New course enrollment** | Next semester | Enrolls in new course; at onboarding, opts to link prior harvest | WF-2 onboarding detects `.axiompack` from prior course; AXI asks: "I see you have research from [prior course]. Would you like your CURIO to reference it?" | New course corpus active; prior harvest loaded as read-only reference corpus for CURIO | New classroom federation membership; prior membership is historical |
| **Cross-course research** | During new course | Runs CURIO research loop; CURIO finds relevant prior findings from harvest | CURIO cites: "In your prior work on [topic], you found [finding] — this contradicts/supports the current query" | Both corpora active: new course (read-write) + prior harvest (read-only) | No cross-federation access; harvest is local to the student's node |
| **Longitudinal identity** | Ongoing | Student's profile accumulates across courses | AXI shows: "You've completed 3 courses using Axiom; here's your learning trajectory" | Longitudinal metrics: topics covered across courses, skill progression, research depth over time | Alumni identity (prd-alumni.md) is the longitudinal thread; each course membership is a timestamped record |
| **Contributing back** | Optional | Student opts to share validated findings with community corpus | CURIO proposes promotion; org-level gate reviews | Finding promoted from student's harvest to Community RAG (with attribution chain preserved) | Promotion uses the current federation membership if enrolled; or standalone contribution via community-federation membership |

### Alumni MVP (bonus deliverable) — what ships with first classroom

1. **Harvest bundle generation** — automated at archive time; `.axiompack` format per §5.9.5.
2. **Harvest bundle loading** — `axi harvest load <path>` makes prior findings available to CURIO as read-only reference.
3. **Cross-course citation** — CURIO's retrieval includes harvest corpus; citations show provenance ("from your Spring 2026 research loop on [topic]").
4. **Longitudinal profile stub** — student's Axiom identity accumulates course participation records (courses completed, dates, harvest sizes). No analytics yet — just the data skeleton.

---

## Gap Analysis: Designed vs. Needs Building

| Capability | Design status | Build status | Journey dependency | Priority |
|------------|--------------|-------------|-------------------|----------|
| Token auth + enrollment provisioning | ✅ Designed (§5.2, §5.11) | ⬜ TODO | All | P0 — blocks everything |
| Open WebUI integration (chat, sessions) | 📋 Spec'd (§5.7) | ⬜ TODO | J1, J2, J3 | P0 |
| Structured Q&A engine | 📋 Spec'd (§5.5) | ⬜ TODO | J1 onboarding, J2 assessment | P0 |
| Course manifest + `.axiompack` | 📋 Spec'd (§5.3) | 🟡 Partial (axiompack format exists) | J2 creation | P0 |
| WF-1 enrollment workflow | 📋 Spec'd (§5.8) | ⬜ TODO | J1, J2, J3 | P0 |
| WF-2 onboarding + readiness | 📋 Spec'd (§5.8) | ⬜ TODO | J1, J3 | P0 |
| Nationality attestation + EC gate | ✅ Designed (§5.11.4) | ⬜ TODO | J3 (EU student) | P0 if Prague has int'l students |
| CURIO research loops | 🟡 Partial (loop exists; classroom integration pending) | 🟡 Partial | J1 active learning | P1 |
| SCAN cadence mode (always-on) | ✅ Designed (§5.11.7) | ⬜ TODO | J1 monitoring, J2 monitoring | P1 |
| Trust policy profiles | ✅ Designed (§5.11.3) | ⬜ TODO | J2 approval management | P1 |
| Classroom-as-ephemeral-federation | ✅ Designed (§5.11.1) | ⬜ TODO | All | P1 |
| Prague EU node + geo-routing | ✅ Designed (prague_deployment) | ⬜ TODO | J3 | P1 if Prague |
| Corpus replication (Rascal → Prague) | 📋 Spec'd (ADR-023 §3) | ⬜ TODO | J3 | P1 if Prague |
| Bonsai narration hooks | ✅ Designed (§5.11.6) | ⬜ TODO | All (UX enrichment) | P2 |
| Quarantine + recovery | ✅ Designed (§5.11.5) | ⬜ TODO | J2 incident response | P2 |
| WF-3..WF-6 (quiz, scoring, check-in, help) | 📋 Spec'd (§5.8) | ⬜ TODO | J1, J2 | P1 |
| WF-10 (submission + grading) | 📋 Spec'd (§5.8) | ⬜ TODO | J1, J2 | P1 |
| Canvas integration | 📋 Spec'd (§5.8 WF-1) | ⬜ TODO (CSV export first; API later) | J2 | P2 |
| Harvest bundle generation | 📋 Spec'd (§5.9.5) | ⬜ TODO | J1 archive, J4 alumni | P1 (bonus) |
| Harvest bundle loading | ✅ Designed (Journey 4) | ⬜ TODO | J4 alumni | P2 (bonus) |
| CURIO cross-course citation | ✅ Designed (Journey 4) | ⬜ TODO | J4 alumni | P2 (bonus) |
| Longitudinal profile stub | ✅ Designed (Journey 4) | ⬜ TODO | J4 alumni | P2 (bonus) |
| LangFuse integration | 📋 Spec'd (§5.1) | ⬜ TODO | J2, J3 (analytics) | P0 |
| WF-7..WF-9, WF-11 | 📋 Spec'd (§5.8) | ⬜ TODO | Post-MVP | P3 |

---

## Interaction Matrix — Three Axes Per Phase (added 2026-04-16)

> Per Ben: "Pay close attention to Instructor, Student personas and
> where they must interact: I↔S, S↔S, I↔I. These interactions must
> be excellent and very well tested."

| Phase | I↔S (Instructor ↔ Student) | S↔S (Student ↔ Student) | I↔I (Instructor ↔ Instructor) |
|-------|---------------------------|------------------------|------------------------------|
| **Enrollment** | Instructor provisions; student receives token + syllabus. AXI mediates. Canvas roster sync bidirectional. | None yet (students don't know each other) | Course template sharing (if co-teaching or reusing prior instructor's template) |
| **Onboarding** | AXI reports per-student checklist to instructor; instructor marks ready/follow-up. | None (onboarding is individual) | Co-instructor reviews of onboarding completion dashboard |
| **Active learning** | SCAN alerts instructor on `student_stuck`; instructor initiates check-in; AXI delivers feedback. Grades pushed to Canvas. | **CURIO cross-pollination:** Student A's validated finding appears in Student B's retrieval. Peer research-loop awareness: "2 classmates also researched [topic]; here's what they found." | Multiple instructors see same cohort dashboard; co-grading; shared course-improvement proposals from CURIO cascade |
| **Assessments** | Instructor administers quiz; scores pushed to Canvas; student sees results + Bonsai-narrated feedback. LLM-suggested scores reviewed by instructor. | Cohort-level anonymized comparison: "your score on objective X was above/below cohort average." NO individual comparison. | Cross-section grade calibration (if multiple sections of same course) |
| **Check-ins** | Scheduled AXI Q&A; SCAN-triggered signal→instructor notification; instructor responds via chat or dashboard. | None (check-ins are private I↔S) | Instructor-to-instructor: "Student X is struggling; has your section seen similar?" (cross-section, same course) |
| **Presentations** | Instructor evaluates; CURIO assists scoring via rubric. | **Peer feedback:** students rate/comment on peers' presentations (WF-11). Feedback anonymized or attributed per course policy. High-quality presentations indexed into course RAG. | Instructor reviews peer-feedback aggregates |
| **Completion** | Final assessment; end-of-course interview; Canvas grade finalization. | Cohort-level reflection: anonymized aggregate of what the cohort learned, struggled with, improved on. | Cross-cohort comparison for course-template refinement |
| **Archive / Alumni** | Instructor initiates archive; harvest bundles distributed. | Alumni cross-pollination: students from different cohorts of the same course can opt-in to share validated findings. | Instructors across semesters share course-template improvements |

### Test coverage per interaction axis

**I↔S tests** (simulated instructor + student in same classroom federation):
- Enrollment: instructor provisions → student receives token → student accesses → instructor sees "enrolled"
- Check-in: SCAN signal → instructor notification → instructor response → student receives
- Grading: score import/auto-score → Canvas grade push → student sees result
- Help: student requests → AXI routes to instructor → instructor responds → student sees resolution
- Quarantine: instructor quarantines → student's session drops → recovery → student re-accesses

**S↔S tests** (two students in same classroom federation):
- Cross-pollination: student-1 validates finding → finding enters classroom RAG → student-2's CURIO retrieves it within one sync cycle
- Peer feedback: student-1 presents → student-2 submits feedback → instructor sees aggregate
- Privacy: student-1 CANNOT see student-2's raw sessions, assessments, or personal check-in responses
- Corroboration: two students independently validate same fact → maturity level increases

**I↔I tests** (two instructors, same or related courses):
- Template sharing: instructor-A publishes course template → instructor-B discovers and adopts (via federation)
- Co-grading: both instructors score same submission → reconciliation workflow
- Cross-cohort patterns: CURIO proposes improvement from cohort-A → instructor-B reviews for applicability

---

## Canvas Integration (required — updated 2026-04-16)

> Per Ben: "Assume Canvas will be used and must be integrated with."

Canvas API integration is **P0/P1**, not post-MVP. Adapter design
follows the ADR-012 provider pattern (swappable for Moodle/
Blackboard later).

**Canvas adapter scope:**

| Operation | Canvas API endpoint | Direction | When |
|-----------|-------------------|-----------|------|
| Roster sync | `GET /courses/:id/enrollments` | Canvas → Axiom | WF-1: enrollment; ongoing for add/drop |
| Grade push | `PUT /courses/:id/assignments/:id/submissions/:id` | Axiom → Canvas | WF-4, WF-10: after scoring |
| Assignment creation | `POST /courses/:id/assignments` | Axiom → Canvas | WF-1: from Course manifest assessments |
| Student info | `GET /users/:id/profile` | Canvas → Axiom | Enrollment: populate student metadata |
| Enrollment changes | `GET /courses/:id/enrollments` (polling) or webhook (if available) | Canvas → Axiom | Ongoing: detect add/drop → update federation membership |

**Auth:** Canvas OAuth2 (institutional developer key). UT has
Canvas API access; Prague instance may use separate Canvas
instance or shared UT Canvas.

**Test strategy:** Canvas API mock (for unit + federation lifecycle
tests) + Canvas sandbox (for integration tests, live API).

---

## Implementation Order (classroom-driven, updated 2026-04-16)

**P0 — Foundation (blocks all journeys):**
Token auth → Open WebUI integration → LangFuse tracing → **Canvas adapter (roster sync + grade push)** → Structured Q&A → Course manifest + axiompack → WF-1 enrollment (Canvas-integrated) → WF-2 onboarding

**P1 — Active classroom (blocks Prague deployment):**
CURIO classroom integration → WF-3..WF-6 + WF-10 (assessment + grading, Canvas-integrated) → SCAN cadence mode → Trust profiles → Classroom federation lifecycle → **I↔S + S↔S interaction flows + tests** → (if Prague) nationality gate + EU node + corpus replication

**P1-bonus — Alumni foundation (ships alongside P1):**
Harvest bundle generation (at archive time) → Harvest bundle loading

**P2 — Enrichment (post-Prague-launch):**
Bonsai narration → Quarantine + recovery → WF-11 (presentations + peer feedback) → **I↔I interaction flows** → Cross-course citation → Longitudinal profile → Platform cascade

**P3 — Full vision:**
WF-7..WF-9 → Federation topologies B–D → Alumni persistent identity → Full Canvas webhook integration
_Copyright (c) 2026 The University of Texas at Austin and B-Tree Labs. Apache-2.0 licensed._
