How to read these docs

These docs are written for three audiences at once. The same content serves all three, but the optimal path through it differs.

If you’re an operator

You want the stack running on your hardware, behind your domain, with your data, and you want to keep it running.

Read in order:

1. What is Scani — five-minute orientation.
2. Quickstart — proves the local stack boots.
3. Tier model — pick how much you want to host yourself.
4. Production with docker-compose — the one-box deploy.
5. Required environment variables — the must-set list.
6. TLS & reverse proxy — Caddy and nginx examples.
7. Managed Postgres / Redis / S3 — when you outgrow the in-compose data plane.
8. Backup & restore, then Upgrades & version pinning.
9. Observability and Troubleshooting when something misbehaves.

You can skip the Concepts cluster entirely if you only operate the stack and never read user-facing data. You’ll want the Glossary within reach the first time a user asks “why does this holding say partial coverage”.

If you’re a contributor

You’re reading the code, planning a change, or shipping a PR.

Read in order:

1. Mental model — the one-pager for the domain.
2. The Concepts page closest to the area you’re touching (Holdings, Transactions, Pricing, …).
3. The matching Design decision page — the why behind the shape of the code, so you don’t undo a load-bearing choice by accident.
4. Engineering conventions, then the DI pattern and Testing patterns pages. These cover the silent footguns: typedi without paramtypes metadata, the stubbed-DI test pattern, env-var ownership.
5. The relevant how to add a … page — provider, job, or migration.
6. How to contribute for the PR mechanics.

The Repo layout and Database schema pages live in Reference but read like a map of the code — skim them once early.

If you’re an LLM (or an agent operating one)

Scani’s docs are optimised to be useful inside a context window.

Start with:

• LLM-friendly index — a copy-pasteable overview of what’s where, the same shape as llms.txt. Also published verbatim at /llms.txt on the docs site.
• /llms-full.txt — every page’s body concatenated, for one-shot ingestion when context allows.
• Glossary — single-page authoritative definitions; cite as glossary#<term-slug>.
• Database schema, tRPC route catalogue, and Job catalogue — these are the highest-value pages for grounding code suggestions.

Citation conventions:

• Every page heading has a stable slugged anchor. They are part of the contract — link with confidence.
• Concept pages always carry a top-of-page Summary; that text is what ends up in llms.txt.
• “See also” links at the bottom of each page form an explicit cross-reference graph.

If you’re none of the above

You probably want What is Scani, then the Glossary to look up any term that’s unfamiliar.

A note on tone

These docs assume you’d rather read a precise paragraph than a hand-holding tutorial. Pages are short, every term that has a definition is linked to the Glossary, and every design choice that surprised the team has a why note.

If a page feels too dense, that’s a bug — please open an issue with the page slug and what you tried to do.