This is the entry point for design documentation. Each document below is self-contained: an agent assigned to a task should read only the document(s) relevant to that task, not the whole set.
Source of truth for product intent: /README.md (repo root). These docs
translate that intent into concrete, buildable specs. If a doc and the
root README conflict, the root README's intent wins -- file a note in
the doc and ask the human, don't silently pick one.
| If you are building... | Read |
|---|---|
| The Python backend skeleton, app structure, FastAPI wiring | 01-backend-architecture.md |
| Login, sessions, rate limiting, password storage, CSRF | 02-auth-and-security.md |
| Database schema, migrations, ORM models | 03-database.md |
| The invoicing feature (admin + customer endpoints) | 04-invoices.md |
| The budget / expense-ledger feature | 05-budget.md |
| The personal inventory feature | 06-inventory.md |
| The TypeScript/Tailwind frontend app shell | 07-frontend-architecture.md |
| The Rust/WASM ASCII rasterizer | 08-ascii-wasm-renderer.md |
| Visual design, typography, color, motion, accessibility | 09-design-system.md |
| SEO, structured data, AI-agent accessibility | 10-seo-and-agent-accessibility.md |
| Docker Compose, VPS deployment, CI/CD | 11-deployment.md |
| Unit/integration/system tests for any component | 12-testing-strategy.md |
| File storage (evidence/receipts/documents), local vs. R2 vs. NAS | 13-storage-abstraction.md |
| Mileage tracking, quick-capture receipts, documents/CAD tracking, the Android client's API contract | 14-mileage-receipts-documents.md |
| The generic admin data browser/audit log, or logging on any platform (backend/frontend/Android) | 15-admin-tools-and-observability.md |
The strata system model (design/logand-app.strata), trust boundaries, capability audit |
18-strata-system-model.md |
Every component is required to have unit, integration, and end-to-end system tests -- backend and frontend both. 12-testing-strategy.md is not optional reading; every feature doc above links into it for its specific test obligations.
00-overview.md is the only doc every agent should skim first -- it has the repo layout and cross-cutting decisions everything else assumes.
These docs started design-stage, written before any implementation existed. Most now describe a real, built, tested system -- they are kept updated in the same change as the code whenever implementation diverges from what a doc originally said, not left frozen at design time (see ../README.md's own "Status" note). Treat a doc as the current source of truth for its area unless it explicitly says otherwise.
- Database: PostgreSQL.
- Repo layout: monorepo, top-level
backend/,frontend/,wasm-ascii/,android/. - Auth: server-side session cookies (HttpOnly, Secure, SameSite), not JWT.
- Deployment: single VPS via Docker Compose.
See 00-overview.md for the reasoning behind each.