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.
154 lines
5.0 KiB
Markdown
154 lines
5.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
## What you are building
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## Tech stack
|
|
|
|
| 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) |
|
|
|
|
---
|
|
|
|
## Stylesheet
|
|
|
|
An existing stylesheet lives at /stylesheet.css in the repo root. This is the
|
|
authoritative visual style for the application.
|
|
|
|
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
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
---
|
|
|
|
## Build order
|
|
|
|
Follow /docs/implementation-plan.md exactly.
|
|
Do not skip phases. Do not build phase N+1 before phase N passes its
|
|
acceptance criteria.
|
|
|
|
Current phase: **Phase 1 — Infrastructure + ingestion service**
|
|
|
|
---
|
|
|
|
## Session discipline
|
|
|
|
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
|
|
|
|
---
|
|
|
|
## 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=
|
|
```
|