dda20612e9
- Created handover document outlining design decisions and application functionality. - Developed implementation plan detailing phased approach for service development. - Specified ingestion service responsibilities, API surface, and processing pipeline.
8.7 KiB
Handover: employee learning platform
Purpose of this document
This document captures every design decision made before implementation started. It is the authoritative source for rationale. When a spec file is ambiguous, resolve it against this document. Do not ask the human — the answers are here.
What this application does
Employees of a tech company use this platform to build and maintain knowledge of the employee handbook, holacratic structures, and internal processes.
Core mechanics:
- Admins upload source documents → AI extracts a structured knowledge base
- The KB is organised into Themes (broad) and Topics (specific)
- An AI generates 10 types of micro learning content per Topic
- Employees follow a 26-week curriculum of weekly sessions
- Each session covers one Theme (multiple related Topics)
- Employees choose which micro learning type to use per Topic
- After 26 weeks the curriculum restarts, varied to reinforce rather than repeat
- A chatbot called R42 answers KB-grounded questions on every screen
- A gamification system using developer-native language motivates completion
All confirmed design decisions
Knowledge base
Decision: KB is extracted from source documents, not manually authored Admins upload raw source material. Claude Sonnet 4 extracts Themes, Topics, and relationships. Admins review and approve in batches (one Theme at a time, not one Topic at a time). Topic bodies are AI-drafted and admin-editable after approval.
Decision: two-level hierarchy — Theme → Topic A Theme is a broad subject area. A Topic is one specific concept within a Theme. One weekly session = one Theme. Multiple Topics within that Theme per session.
Decision: three relationship types between Topics
- related: Topics that complement each other
- prerequisite: Topic A should be understood before Topic B
- contrast: Topics representing opposing approaches
These relationships are stored as explicit PocketBase relation fields, not a generic junction table.
Decision: source material format priority Accepted formats: PDF, MD, TXT only. MD is the highest quality input — heading structure maps directly to Theme → Topic hierarchy. Admins should be recommended to provide MD where possible.
Decision: embeddings from source chunks, not topic summaries only R42 retrieves from original source material chunks as primary source, with topic summaries as secondary. This keeps R42 grounded and reduces hallucination.
Micro learnings
Decision: 10 types, all generated by AI as structured JSON Types:
- concept_explainer
- scenario_quiz
- misconceptions
- how_to
- comparison_card
- reflection_prompt
- flashcard_set
- case_study
- glossary_anchor
- myth_vs_evidence
Each type has a defined JSON schema in data-model.md. Generation uses Claude Sonnet 4. Output is validated against Zod schemas before storage.
Decision: employees choose type per topic per session Employees are not locked to one type globally. Each session, per Topic, the employee selects from all published types for that topic. Multiple types can be completed in one session.
Decision: pre-generate, don't generate on demand All 10 types are generated when a Topic is approved, not when an employee requests them. This controls quality and cost. R42 is the only on-demand AI interaction.
Curriculum
Decision: AI generates curriculum, admin edits Claude Sonnet 4 reads the full KB graph (Themes, Topics, relationships, complexity weights) and produces a 26-week schedule. Admin reviews, reorders, and finetunes. Admin does not build from scratch.
Decision: one Theme per week session A session covers all Topics under one Theme. Topics within the session are ordered by the curriculum generator based on prerequisites and complexity.
Decision: perpetual curriculum with versioning The curriculum runs indefinitely. After week 26, cycle 2 begins on the latest curriculum version. Cycle 2+ varies sequence, surfaces unused micro learning types, and increases coverage of low-engagement topics.
Decision: completed weeks are immutable Regeneration only affects future unstarted weeks. An employee's completion history is never altered regardless of curriculum version changes.
Decision: regeneration requires admin confirmation When new Topics are approved, the system queues a regeneration but does not apply it until the admin explicitly confirms. Admin sees a preview of the proposed new schedule before confirming.
Decision: rolling starts Each employee has their own start date. There are no cohorts or shared start dates.
Gamification
Decision: developer-native visual language Inspired by GitHub (heatmap), Stack Overflow (badges, reputation), and Duolingo (streak, XP, levels). Language uses developer vocabulary throughout.
Decision: XP unit is called commits Every completed Topic earns commits. Quantity varies by micro learning type.
Decision: levels use developer rank names Intern → Junior → Medior → Senior → Staff → Principal Based on cumulative commits across all cycles.
Decision: streak is weekly, not daily Consecutive weeks with at least one completion. Resets on a skipped week.
Decision: activity heatmap covers 26-week cycle GitHub-style contribution graph. Cell darkness = number of types completed that week.
Decision: no social layer No comments, reactions, or direct messaging. Gamification is visible but not interactive between employees.
Decision: public milestone cards, not ranked leaderboard At weeks 13 and 26, a public card is posted to the shared activity feed. Language: "shipped", not "graduated". The leaderboard shows multiple dimensions (commits, streak, types used, badges) — not a single ranking.
Decision: named content badges Examples: governance_nerd, process_architect, deep_reader. These are seeded at startup, not user-generated. See data-model.md for badge schema.
R42 chatbot
Decision: functional only, no personality R42 answers questions grounded in the KB. It does not have a defined persona, tone, or name story beyond the label R42.
Decision: stateless per session No chat history is persisted between sessions. This avoids privacy complexity and keeps the implementation simple.
Decision: internal KB scope only R42 cannot search external sources. If a question cannot be answered from the KB, R42 says so explicitly.
Decision: context-weighted retrieval R42 knows the employee's current curriculum week. Retrieval boosts chunks from the current week's Theme. General KB questions are not restricted.
Decision: always cites source Topic Every R42 response includes the Topic title(s) its answer draws from.
Decision: Haiku 4.5 for R42, Sonnet 4 for generation Low latency matters for chat. The retrieval layer compensates for Haiku's smaller knowledge base. Sonnet 4 is reserved for generation tasks where structure and quality matter more than speed.
Infrastructure
Decision: PocketBase as primary backend Auth, file storage, structured data, and admin UI in one binary. SQLite is sufficient for ~150 users. No PostgreSQL needed at this scale.
Decision: Qdrant for vector storage Separate Docker container. Keeps vector operations out of SQLite. pgvector was rejected — adding Postgres just for vectors is unnecessary overhead.
Decision: Next.js 14 PWA for frontend Single codebase for admin and employee app. PWA covers mobile without a native app. Learning platforms do not require native device APIs.
Decision: five discrete backend services Ingestion, generation, curriculum, chat, progress. Each is a separate Fastify service with its own port and responsibility. They do not call each other directly — they read/write shared PocketBase collections.
Decision: PDF parsing starts with pdf-parse (Node.js) Switch to pdfplumber Python sidecar only if pdf-parse quality is insufficient for actual source documents. Do not over-engineer the extraction layer upfront.
What is not yet specced
The following spec files still need to be written before their phases begin:
- /docs/generation-spec.md — micro learning generation service
- /docs/curriculum-spec.md — curriculum generator + versioning
- /docs/r42-spec.md — chat service
- /docs/gamification-spec.md — progress service + gamification mechanics
- /docs/frontend-spec.md — employee app, admin app, PWA config
Do not begin a phase without its spec file. Flag the gap if you reach it.
Source of truth hierarchy
When sources conflict, resolve in this order:
- This handover document (rationale and decisions)
- The relevant spec file (implementation detail)
- data-model.md (schema is authoritative)
- architecture.md (system structure)
Do not use legacy/ code as a source of truth for anything.