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.
232 lines
8.7 KiB
Markdown
232 lines
8.7 KiB
Markdown
# 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:
|
|
1. concept_explainer
|
|
2. scenario_quiz
|
|
3. misconceptions
|
|
4. how_to
|
|
5. comparison_card
|
|
6. reflection_prompt
|
|
7. flashcard_set
|
|
8. case_study
|
|
9. glossary_anchor
|
|
10. 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:
|
|
1. This handover document (rationale and decisions)
|
|
2. The relevant spec file (implementation detail)
|
|
3. data-model.md (schema is authoritative)
|
|
4. architecture.md (system structure)
|
|
|
|
Do not use legacy/ code as a source of truth for anything.
|