# Architecture diagrams

Hand-authored SVG, one per subject. The SVG **is** the artifact: no diagram
toolchain, no build step, and it renders anywhere a browser or an IDE preview
does. Each file carries its own stylesheet and follows the reader's light or
dark mode through `prefers-color-scheme`.

**Maintenance rule:** diagrams are as-is documentation like the rest of
`docs/`. When a change lands that affects them, the diagram is edited in the
same change: a stale diagram is a bug. Where docs and code disagree, the code
wins and the doc gets fixed in the same commit.

**Editing:** every box is a `<rect>` plus its `<text>` lines at explicit
coordinates on a plain grid, so a label change is a text edit and a new box is
a copied block with new numbers. Keep the shared `<style>` block identical
across the five files so they stay one visual system.

| Diagram | Shows |
|---|---|
| [data-model.svg](data-model.svg) | ER diagram of all 13 tables, FK semantics, uniques (mirrors the actual migrations) |
| [components.svg](components.svg) | System components and their dependencies; built vs. planned (dashed) |
| [auth-sequence.svg](auth-sequence.svg) | Login (argon2, session row, httpOnly cookie) and per-request validation incl. the 401 to redirect branch |
| [queue-sequence.svg](queue-sequence.svg) | Job queue: claim via FOR UPDATE SKIP LOCKED, handler inside the open claim transaction, backoff, crash safety |
| [retrieval-sequence.svg](retrieval-sequence.svg) | Hybrid retrieval, the text-only fallback, and the similarity path: permission CTE first in every one of them |