Design overview
Forward-looking design for this project's content-browse platform direction. Hand-written; separate from the auto-generated API reference (../api-reference/) and the auto-generated architecture (../generated/), both of which are produced from source by scripts/gen-docs.sh.
When implementation drifts from these docs, fix one or the other — never leave them inconsistent.
Structure
Three tiers:
- Philosophy & contracts — what we're building; what the HTTP shapes look like.
- Cross-cutting architecture & ops — how the code is organized, run, and secured.
- Per-feature implementation notes (
features/) — focused answers to "I'm building or touching X; what do I need to know?"
Tier 1 — Philosophy & contracts
| Doc | Read when |
|---|---|
| AgnosticUI | Thinking about the browse UX. Single-kind, Chrome-extension-adapted. |
| Taxonomy | Before adding an entity or index. Content, Tag, Surface, Group, Channel, Platform. |
| API | Before adding an endpoint. Response envelope, pagination, slugs, errors, catalog, search. |
| Auth | Before adding a guard or role/permission. JWT + refresh, Chrome storage. |
| Config | Before adding an env variable, or when renaming the project. /meta endpoint. |
Tier 2 — Cross-cutting
| Doc | Read when |
|---|---|
| Development | Setting up locally, running tests, seeding, debugging. |
| Operations | Deploying or operating. Secrets, logging, backups, runbooks. |
| Security | Threat model, secrets catalog, rate limits, incident response. |
| Extension | Building or debugging the Chrome extension. MV3, surfaces, messaging. |
Tier 3 — Features
See the features overview. One doc per well-bounded feature or mechanism, each following the same section headings: Purpose → Contract → Implementation → Required variables/services → Gotchas → Testing.
Reading paths
- Brand-new contributor → this page → Development → pick a feature doc.
- Building a new endpoint → API → the feature doc for the domain you're touching.
- Operator → Operations → Security → Config.
- Extension developer → Extension → Auth → features/catalog → features/content-search.
Relationship to current implementation
The project's current state (User/Role CRUD, no auth) is documented at the repo root in docs/ARCHITECTURE.md and docs/RUNBOOK.md. The design here describes where the project is heading, not what runs today. CLAUDE.md carries a direction-shift banner pointing to this directory.