learning-platform/docs/handover.md

# Handover: Respellion Learning Platform

## Purpose of this document

This document captures the **design decisions as actually built**. The platform
diverged substantially from its original design vision (a Next.js multi-service
system with Qdrant and OpenAI embeddings). This handover reflects what shipped:
a React/Vite SPA on PocketBase with local TF-IDF retrieval.

When sources conflict, trust the code in `src/` first, then this document, then
`docs/data-model.md` (schema), then `docs/architecture.md`.

---

## What this application does

Employees use the platform to build and maintain knowledge of the company's
internal handbook, roles, and processes.

Core mechanics:
- Admins upload source documents → Claude extracts a structured knowledge graph (topics + relations)
- AI generates learning content and micro-learnings per topic
- Each employee follows a 26-week curriculum, **starting whenever they enroll**
- Each week presents an assigned topic; the employee completes micro-learnings and a test
- After week 26 the cycle restarts at week 1 with the same content
- R42, an AI assistant, answers KB-grounded questions on every screen
- A gamification layer (points, badges, leaderboard) motivates completion

---

## Key decisions as built

### Architecture
- **Single-page React app, not microservices.** All logic runs in the browser
  (`src/`). PocketBase is the only backend; the Anthropic API is reached through a
  reverse proxy (Caddy in prod, Vite in dev). The original `app/` Next.js scaffold
  was abandoned and is not deployed.
- **PocketBase for everything stateful** — auth, structured data, file storage.
  SQLite is sufficient at this scale.
- **No vector database.** Retrieval is a dependency-free TF-IDF index over the
  knowledge graph (`src/lib/retrieval.js`). Qdrant and the embedding service from
  the original design were never built.

### Knowledge base
- **Extracted, not hand-authored.** Admins upload `.txt` / `.md` (≤5 MB). Claude
  (standard tier) extracts topics and relations chunk by chunk.
- **Flat graph, not a Theme→Topic tree.** The KB is `topics` + `relations`. A
  topic's `theme` is a string used for curriculum grouping, not a separate entity.
- **Relation types:** `related_to`, `depends_on`, `part_of`, `executed_by`.
- **Topic relevance** (`core` / `standard` / `peripheral` / `exclude`) controls
  what enters learning/curriculum; `relevance_locked` protects admin overrides on
  re-ingestion.

### Learning content
- **Long-form content is generated on demand**, three types: `article`, `slides`,
  `infographic` (the `content` collection). New types shallow-merge into the cached
  object. **No podcast type.**
- **Micro-learnings**, three types: `concept_explainer`, `scenario_quiz`,
  `flashcard_set` (the `micro_learnings` collection). A former `reflection_prompt`
  type was dropped.
- **Employee chooses the format** per topic per session. Completion is not
  quality-gated; engaging with the full micro-learning counts.

### Curriculum
- **AI generates, admin confirms.** Claude proposes a 26-week schedule from the
  themed/weighted topic set; the admin previews and activates it. Versions move
  `draft → active → superseded`; exactly one is active.
- **Per-user, self-paced start (current behavior).** Each employee enrolls on first
  login; their week/cycle is derived from `curriculum_started_at`. There is **no
  shared calendar week**. Week 1 is the first 7 days after they enroll.
- **Perpetual, repeating cycles.** After week 26, the cycle restarts at week 1 with
  the same content. Completion history (`micro_learning_completions`) is append-only.
- **Hash fallback.** If no curriculum version is active, topic assignment falls back
  to a deterministic hash of user id + week. Keep this fallback.

### R42 chatbot
- **KB-grounded via TF-IDF**, not vector search. Context = top-K topics + verbatim
  mentions + filtered relations + limited deep content.
- **Conversation persists per user** in `localStorage` (cap 50 messages; ~12 turns
  sent to the API). It is not stored server-side.
- **Can propose graph edits** (`propose_graph_delta`, ≤3 topics / ≤5 relations).
  Admins apply immediately; non-admins queue a suggestion for admin approval.
- **Hidden during quizzes** to protect test integrity.

### Gamification
- **Points:** +2 per correct quiz answer, in the `leaderboard` collection.
- **Badges** computed at render time: First Steps (1 test), Veteran (5 tests),
  Perfectionist (a 100% score).
- Admins are excluded from the public leaderboard.

### Auth & infrastructure
- **PIN auth** against `team_members`; the session id lives in `sessionStorage`.
  Role `admin` unlocks the Admin panel.
- **Claude model tiers:** `fast` = Haiku 4.5, `standard` = Sonnet 4.6,
  `reasoning` = Opus 4.7. Admins can override per tier from Settings.
- **Simulation mode** (`admin:use_simulation`) returns stub LLM output for UI work.
- **Deploy:** Docker image (Caddy serving the built SPA) + PocketBase container;
  Ansible playbooks under `infra/` for dev and prod.

---

## Notable divergences from the original vision

| Original design (not built) | What shipped |
|---|---|
| Next.js 14 PWA + 6 Fastify services | Single React/Vite SPA, no backend services |
| Qdrant + OpenAI embeddings | Local TF-IDF, no embeddings |
| Theme/Topic entity hierarchy, batch approval | Flat `topics` + `relations` graph |
| 10 micro-learning types | 3 micro-learning types |
| `employee_curriculum_state`, `badges`, `milestone_cards`, etc. | `team_members` fields + `leaderboard` + render-time badges |
| Shared calendar-week curriculum | Per-user start, self-paced |

The abandoned scaffolding for the original design still exists under `/app` — it is
not part of the running system.