Clean Architecture + Bounded Contexts + grounded AI content preparation.
All current architecture and engineering guidance is under:
Read these first:
- Documentation index
- Architecture
- Domain contracts
- Content authoring and delivery
- Assessment, mastery and learning
- Content ingestion and AI
- AI developer instructions
- Current repository state
The old docs/ directory is temporarily retained as historical source material while the documentation migration is verified. It is not authoritative for new development.
Interface
↓
Application use cases
↓
Domain rules
↑
Infrastructure adapters
↑
Composition root
Educational state:
Assessment → Evidence → Mastery → Learning
PUBLISHED means ready for learner use; it does not mean immutable.
Content may continue to be corrected and enriched after publication through the canonical authoring path.
Publication/readiness is separate from learning-path inclusion. A backend-owned learning-path control is the target contract for deciding whether a published lesson is eligible for guided progression.
npm install
npm run db:dev
cp .env.example .env
npm run db:apply
npm run db:seed
npm run devHealth:
curl localhost:3000/api/v1/healthUse the scripts actually defined in package.json:
npm run typecheck
npm run arch:check
npm test
npm run verifyDo not treat a green typecheck as proof that architecture, persistence, security, or the complete user flow is correct.
- Prisma schema is the persistence source of truth.
- One owner per business decision.
- No duplicate write paths.
- No Prisma/provider SDKs in domain/application.
- Python/content engine never writes PostgreSQL.
- AI never directly writes canonical educational state.
- React renders backend decisions; it does not recreate them.
- Historical learner data is protected.
- Canonical keys never depend on order/index/position.
- Imports are validated, deduplicated, dry-run capable and idempotent.