Add comprehensive documentation for key organizational aspects
- Introduced "Pension Scheme & Benefits" detailing secondary employment benefits and pension specifics. - Created "Roles & Accountabilities" outlining the Holacracy role structure and responsibilities within Respellion. - Added "Security" section covering GDPR compliance and workplace safety protocols. - Established "Spending and Contracting" policy detailing expense categories and submission processes. - Documented "Who We Are" to define Respellion's identity, services, and operational model under Holacracy and ISO 9001.
This commit is contained in:
RaymondVerhoef
224
CLAUDE.md
224
CLAUDE.md
@@ -1,54 +1,16 @@
|
||||
# CLAUDE.md
|
||||
|
||||
## What you are building
|
||||
## What this is
|
||||
|
||||
A mobile-first progressive web application for employee learning. Employees follow
|
||||
a perpetual 26-week curriculum built from an internal knowledge base. An AI
|
||||
assistant called R42 is available on every screen. Admins upload source documents
|
||||
that are processed into the knowledge base by AI.
|
||||
The **Respellion Learning Platform** — an internal AI-powered learning app that
|
||||
keeps employees current with the company's evolving knowledge base. Employees
|
||||
follow a perpetual **26-week curriculum**, each working through weekly learning
|
||||
sessions and tests. An AI assistant called **R42** is available on every screen.
|
||||
Admins upload source documents that Claude extracts into a knowledge graph.
|
||||
|
||||
Read the full design before writing any code:
|
||||
- /docs/handover.md — all decisions made, rationale, constraints
|
||||
- /docs/architecture.md — system design, data flows, tech stack
|
||||
- /docs/data-model.md — all PocketBase collections, Qdrant schema, types
|
||||
- /docs/ingestion-spec.md — ingestion service (build this first)
|
||||
- /docs/implementation-plan.md — ordered build sequence with acceptance criteria
|
||||
|
||||
---
|
||||
|
||||
## Absolute constraints
|
||||
|
||||
These rules are non-negotiable and apply to every session:
|
||||
|
||||
1. Never modify any file listed in PROTECTED.md
|
||||
2. Never modify any file outside /app — the pipeline, Dockerfile, ansible,
|
||||
and docker-compose files are frozen
|
||||
3. Never delete files without explicit confirmation
|
||||
4. Never change package.json scripts that contain 'deploy' or 'build:prod'
|
||||
5. Ask before acting when scope is unclear — do not infer intent from legacy/ code
|
||||
|
||||
---
|
||||
|
||||
## Repository structure
|
||||
|
||||
```
|
||||
repo/
|
||||
├── CLAUDE.md ← you are here
|
||||
├── PROTECTED.md ← files you must never touch
|
||||
├── docs/ ← spec files — read, never modify
|
||||
├── legacy/ ← old prototype — read-only reference only
|
||||
└── app/ ← your working directory
|
||||
├── frontend/ ← Next.js 14 PWA
|
||||
└── services/
|
||||
├── ingestion/ ← build first
|
||||
├── generation/ ← build second
|
||||
├── curriculum/ ← build third
|
||||
├── embedding/ ← integrated into ingestion, separate later
|
||||
├── chat/ ← R42
|
||||
└── progress/ ← gamification
|
||||
```
|
||||
|
||||
All work happens inside /app. No exceptions.
|
||||
This is a **single-page React application** (Vite) backed by **PocketBase**.
|
||||
There is **no separate backend** — all logic runs in the browser and talks
|
||||
directly to PocketBase collections and (via a proxy) the Anthropic API.
|
||||
|
||||
---
|
||||
|
||||
@@ -56,98 +18,124 @@ All work happens inside /app. No exceptions.
|
||||
|
||||
| Layer | Technology |
|
||||
|---|---|
|
||||
| Frontend | Next.js 14, TypeScript strict, Tailwind CSS, PWA |
|
||||
| Backend state | PocketBase (binary, not source — do not scaffold from scratch) |
|
||||
| Vector store | Qdrant via REST client |
|
||||
| AI generation | Claude Sonnet 4 — model string: claude-sonnet-4-20250514 |
|
||||
| AI chat (R42) | Claude Haiku 4.5 — model string: claude-haiku-4-5-20251001 |
|
||||
| Embeddings | OpenAI text-embedding-3-small |
|
||||
| Services | Node.js, Fastify, TypeScript strict |
|
||||
| Validation | Zod on all external data (API responses, AI output, PocketBase) |
|
||||
| Frontend | React 19 + Vite 8, React Router 7 |
|
||||
| Styling | Vanilla CSS (CSS custom properties) + Tailwind v4 utilities mapped to those variables |
|
||||
| Animation | Framer Motion |
|
||||
| Icons | Lucide React |
|
||||
| Graph viz | D3.js (admin knowledge graph only) |
|
||||
| Backend / DB / auth | PocketBase (self-hosted, SQLite) |
|
||||
| AI | Anthropic Claude via a reverse-proxy (Caddy in prod, Vite proxy in dev) |
|
||||
| Retrieval (RAG) | Local TF-IDF over the knowledge graph — **no Qdrant, no embeddings API** |
|
||||
| Validation | Zod on all AI tool output |
|
||||
| Infra | Docker + Caddy; Ansible playbooks under `infra/` |
|
||||
|
||||
**Claude models** (`src/lib/llm.js`, by tier):
|
||||
- `fast` → `claude-haiku-4-5-20251001` (R42 chat, quiz batches, flashcards)
|
||||
- `standard` → `claude-sonnet-4-6` (extraction, article/slides/infographic, curriculum)
|
||||
- `reasoning` → `claude-opus-4-7`
|
||||
|
||||
Admins can override any tier's model string from the Settings tab (persisted in
|
||||
localStorage as `admin:model:{tier}`).
|
||||
|
||||
---
|
||||
|
||||
## Stylesheet
|
||||
## Repository structure
|
||||
|
||||
An existing stylesheet lives at /stylesheet.css in the repo root. This is the
|
||||
authoritative visual style for the application.
|
||||
```
|
||||
repo/
|
||||
├── CLAUDE.md ← you are here
|
||||
├── AI_AGENT.md ← detailed architecture/patterns guide — read this
|
||||
├── README.md ← quickstart
|
||||
├── PROTECTED.md ← files you must not modify
|
||||
├── docs/ ← spec files (describe the system as built)
|
||||
├── src/ ← THE APPLICATION (React/Vite)
|
||||
│ ├── pages/ ← route screens (Dashboard, Leren, Testen, Leaderboard, Login, Onboarding, Admin/)
|
||||
│ ├── components/ ← ui primitives, admin panels, chat (R42), micro_learning
|
||||
│ ├── lib/ ← services: llm, db, extractionPipeline, learningService,
|
||||
│ │ microLearningService, testService, curriculumService, retrieval, pb
|
||||
│ ├── hooks/ ← React hooks
|
||||
│ └── store/ ← AppContext (global state)
|
||||
├── pb_migrations/ ← PocketBase schema migrations (JS, applied by the PB binary)
|
||||
├── scripts/ ← setup-pb-collections.mjs (local collection bootstrap)
|
||||
├── public/ ← static assets, fonts
|
||||
├── infra/ ← Ansible deploy playbooks (development / production)
|
||||
├── Caddyfile, Dockerfile, docker-compose.yml ← deployment (frozen)
|
||||
└── stylesheet.css ← authoritative visual reference (frozen)
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Never modify stylesheet.css
|
||||
- Import it as a global stylesheet in the Next.js frontend
|
||||
- Do not override its rules with Tailwind utility classes or inline styles
|
||||
- When Tailwind and the stylesheet conflict, the stylesheet wins
|
||||
- If a UI element is not covered by the stylesheet, use Tailwind — but match
|
||||
the visual language (spacing, colour, type scale) of the existing stylesheet
|
||||
> **Note on `/app`:** the top-level `app/` directory is **abandoned scaffolding**
|
||||
> from the original Next.js + Qdrant design that was never shipped. It is not
|
||||
> wired into `package.json`, Vite, or Docker. **Ignore it.** The real app is `/src`.
|
||||
|
||||
---
|
||||
|
||||
## Absolute constraints
|
||||
|
||||
1. Never modify any file listed in `PROTECTED.md`.
|
||||
2. Never modify `stylesheet.css` — it is the authoritative visual reference. Use the
|
||||
CSS variables in `src/index.css` and the Tailwind classes mapped to them.
|
||||
3. Treat the deployment files as frozen unless explicitly asked: `Dockerfile`,
|
||||
`Caddyfile`, `docker-compose.yml`, `infra/`, `.github/workflows/`.
|
||||
4. Never delete files without explicit confirmation.
|
||||
5. Never re-enable PocketBase auto-cancellation — `pb.autoCancellation(false)` in
|
||||
`src/lib/pb.js` is deliberate (see AI_AGENT.md §2).
|
||||
6. There is **no podcast** learning type. It was removed. Do not re-add it.
|
||||
7. Ask before acting when scope is unclear.
|
||||
|
||||
---
|
||||
|
||||
## Code conventions
|
||||
|
||||
- TypeScript strict mode everywhere — no `any` types
|
||||
- All Claude API responses validated through Zod before use
|
||||
- All PocketBase writes typed against collection schemas in data-model.md
|
||||
- Qdrant payloads explicitly typed — no untyped objects
|
||||
- No inline hardcoded API keys — environment variables only
|
||||
- REST conventions for all service APIs
|
||||
- Mobile-first CSS — design for 375px width, scale up
|
||||
- All `src/lib/db.js` functions are `async` — always `await` them.
|
||||
- All Claude tool output is validated through Zod (`src/lib/llmSchemas.js`) before use.
|
||||
Never reach `/api/anthropic` directly — go through `callLLM` in `src/lib/llm.js`.
|
||||
- No client-side API key. The Anthropic key is injected server-side by the proxy.
|
||||
- Reuse the UI primitives in `src/components/ui/` (`Card`, `Button`, `Tag`, `Input`).
|
||||
- Mobile-first — the employee app targets 375px width and scales up.
|
||||
- No hardcoded hex colors; use the design-system CSS variables / Tailwind tokens.
|
||||
|
||||
---
|
||||
|
||||
## Build order
|
||||
## Running locally
|
||||
|
||||
Follow /docs/implementation-plan.md exactly.
|
||||
Do not skip phases. Do not build phase N+1 before phase N passes its
|
||||
acceptance criteria.
|
||||
```bash
|
||||
npm install
|
||||
./pocketbase.exe serve # or the muchobien/pocketbase Docker image
|
||||
node scripts/setup-pb-collections.mjs # first run only — bootstraps collections
|
||||
npm run dev # Vite dev server (proxies /api/anthropic)
|
||||
```
|
||||
|
||||
Current phase: **Phase 1 — Infrastructure + ingestion service**
|
||||
Set `ANTHROPIC_API_KEY` in the environment so the Vite proxy can inject it
|
||||
(`vite.config.js`). PocketBase migrations in `pb_migrations/` apply automatically
|
||||
when the PB binary starts.
|
||||
|
||||
| Command | Purpose |
|
||||
|---|---|
|
||||
| `npm run dev` | Vite dev server |
|
||||
| `npm run build` | Production build to `dist/` |
|
||||
| `npm test` | Vitest unit tests |
|
||||
| `npm run lint` | ESLint |
|
||||
|
||||
---
|
||||
|
||||
## Session discipline
|
||||
## Documentation map
|
||||
|
||||
Each session has a defined scope in implementation-plan.md.
|
||||
At the start of each session:
|
||||
1. State which phase and step you are working on
|
||||
2. Read the relevant spec file(s)
|
||||
3. Propose a file structure or change plan before writing code
|
||||
4. Implement after the plan is clear
|
||||
|
||||
At the end of each session:
|
||||
1. State what was completed
|
||||
2. State what acceptance criteria have been met
|
||||
3. State what the next session should start with
|
||||
- `AI_AGENT.md` — detailed patterns, gotchas, and subsystem guide. **Start here for any real work.**
|
||||
- `docs/architecture.md` — system design and data flows
|
||||
- `docs/data-model.md` — every PocketBase collection and field
|
||||
- `docs/ingestion-spec.md` — upload → knowledge-graph extraction
|
||||
- `docs/generation-spec.md` — learning content + micro-learning generation
|
||||
- `docs/curriculum-spec.md` — 26-week per-user curriculum engine
|
||||
- `docs/r42-spec.md` — the R42 chatbot
|
||||
- `docs/frontend-spec.md` — screens, routing, onboarding
|
||||
- `docs/gamification-spec.md` — points, badges, leaderboard
|
||||
- `micro-learning-spec.md` — micro-learning learner experience
|
||||
|
||||
---
|
||||
|
||||
## When you are uncertain
|
||||
|
||||
Check the spec files in /docs first.
|
||||
If the spec does not cover it, flag the gap explicitly rather than making
|
||||
an assumption. Do not look at legacy/ code for implementation guidance —
|
||||
it is a different stack and will lead you in the wrong direction.
|
||||
|
||||
---
|
||||
|
||||
## Environment variables
|
||||
|
||||
Each service has its own .env file. Templates are defined in each service spec.
|
||||
Never commit actual values. Always use .env.example with placeholder values.
|
||||
|
||||
The full set across all services:
|
||||
```
|
||||
ANTHROPIC_API_KEY=
|
||||
OPENAI_API_KEY=
|
||||
POCKETBASE_URL=
|
||||
POCKETBASE_ADMIN_EMAIL=
|
||||
POCKETBASE_ADMIN_PASSWORD=
|
||||
QDRANT_URL=
|
||||
QDRANT_API_KEY=
|
||||
INGESTION_PORT=3001
|
||||
GENERATION_PORT=3002
|
||||
CURRICULUM_PORT=3003
|
||||
CHAT_PORT=3004
|
||||
PROGRESS_PORT=3005
|
||||
NEXT_PUBLIC_API_URL=
|
||||
NEXT_PUBLIC_POCKETBASE_URL=
|
||||
```
|
||||
Check the spec files in `docs/` and `AI_AGENT.md` first. If the spec does not
|
||||
cover it, read the actual code in `src/` — it is the source of truth. Flag gaps
|
||||
explicitly rather than assuming. Do not treat the abandoned `/app` scaffolding or
|
||||
`legacy`-style references in old comments as guidance.
|
||||
|
||||
Reference in New Issue
Block a user