Documentation Index
The map to every doc in this repository — what each one covers, a reading order by role, and where to look for a specific topic.
Tip
Run task docs to render all of these into a browsable, themed HTML site under docs-site/ (sidebar, per-page table of contents, search via your browser).
All documents
| Document | What it covers | Best for |
|---|---|---|
| README | Project overview, quick start, configuration | First-time readers |
| API Reference | Every endpoint, auth, errors, examples | API & frontend devs |
| Architecture | System design, data flow, schema, patterns | Architects, senior devs |
| Codebase Structure | Directory and file layout | Navigating the code |
| Code Documentation | Packages, types, functions | Reading the code |
| Development | Setup, testing, building, debugging | Backend devs |
| Contributing | Workflow, standards, commits, PRs | Contributors |
| Security | Auth model, hardening, checklist | Security review, ops |
| Deployment | Production deploy and operations | DevOps |
| Implementation Summary | Hardening record, what shipped after, known limitations | Status snapshot |
| Review Checklist | Review criteria for the hardening controls and the application layer | Reviewers |
Start here, by role
| If you're a… | Read in this order |
|---|---|
| Frontend / API consumer | README → API Reference → Security (auth) |
| New backend developer | README → Development → Codebase Structure → Code Documentation → Architecture |
| Architect / tech lead | Architecture → Security → Implementation Summary → Deployment |
| DevOps / operator | Deployment → .env.example → Security → Architecture |
| Contributor / reviewer | Contributing → Review Checklist → Development |
Find a topic
Authentication & security — how to authenticate (API Reference) · session/CSRF model and hardening (Security)
Roles & permissions — what readers, authors, and admins may do (Code Documentation) · how the route groups enforce it (Architecture)
Password reset & email verification — endpoints (API Reference) · token handling and enumeration safety (Security) · running the flows without a mail server (Development)
Comments, likes & follows — endpoints (API Reference) · authorization rules (Code Documentation) · review criteria (Review Checklist)
Notifications & realtime (SSE) — the /events stream (API Reference) · the hub and its single-instance limit (Code Documentation) · proxying it in production (Deployment)
Direct messaging — endpoints (API Reference) · service and schema notes (Code Documentation)
Search — the /search endpoint (API Reference) · the full-text index (Architecture)
Email / SMTP — configuration (Deployment) · the mailer (Code Documentation) · local development (Development)
API endpoints — all endpoints (API Reference) · handlers and services (Code Documentation)
Database — schema and data flow (Architecture) · queries and models (Code Documentation) · migrations (Development)
Configuration — every option (.env.example) · the essentials (README)
Running & testing — local setup, tests, builds (Development)
Deployment — production setup and ops (Deployment)
Code organization — directory layout (Codebase Structure) · architecture patterns (Architecture)
About these docs
The Markdown files in the repository root are the source of truth. The HTML site under docs-site/ is generated from them by tools/docsgen (task docs) — edit the Markdown, then regenerate. When you change code, update the docs in the same PR.