# Crown system docs

This content powers the self-contained Crown docs app in `apps/docs-site/`.

The docs are split into two parts:

- **Human-written pages** — explain the system, deployment model, database patterns, and maintenance workflow.
- **Generated diagrams and summaries** — regenerated from the workspace, Docker Compose files, and source usage patterns so they stay aligned with the codebase.

## Start here

- [Public docs landing page](./index.html)
- [System overview](./architecture/system-overview.md)
- [Deployment architecture](./architecture/deployment-architecture.md)
- [Single-server Coolify deployment](./architecture/single-server-coolify-deployment.md)
- [Multi-node Coolify + SurrealDB deployment](./architecture/multi-node-coolify-surrealdb-deployment.md)
- [Ubuntu / Coolify hosted deployment](./architecture/ubuntu-coolify-deployment.md)
- [Service communication](./architecture/service-communication.md)
- [Generated auth runtime summary](./architecture/generated/auth-runtime.md)
- [Generated records-service auth integration](./architecture/generated/records-service-auth-integration.md)
- [Database architecture](./architecture/database-architecture.md)
- [Local development guide](./guides/local-development.md)
- [Publishing the docs site](./guides/publishing-docs.md)
- [Railroad diagrams guide](./guides/railroad-diagrams.md)
- [Adding a service](./guides/adding-a-service.md)
- [Adding a package](./guides/adding-a-package.md)
- [Interactive explorer](./explorer/index.html)

## Choose the right page

| If you want to...                                                              | Start with                                                                                             | Then open                                                                                                                                                                                            |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Understand the monorepo shape                                                  | [System overview](./architecture/system-overview.md)                                                   | [`dependency-graph.svg`](./diagrams/generated/dependency-graph.svg)                                                                                                                                  |
| Understand containers, ports, and startup order                                | [Deployment architecture](./architecture/deployment-architecture.md)                                   | [`service-topology.svg`](./diagrams/generated/service-topology.svg) and [`deployment-order.svg`](./diagrams/generated/deployment-order.svg)                                                          |
| Pick a smallest-possible production host shape                                 | [Single-server Coolify deployment](./architecture/single-server-coolify-deployment.md)                 | [`single-server-coolify-deployment.svg`](./diagrams/generated/single-server-coolify-deployment.svg)                                                                                                  |
| Plan multi-server scale-out with per-server domain routing and clustered data  | [Multi-node Coolify + SurrealDB deployment](./architecture/multi-node-coolify-surrealdb-deployment.md) | [`multi-node-coolify-surrealdb-deployment.svg`](./diagrams/generated/multi-node-coolify-surrealdb-deployment.svg)                                                                                    |
| Understand Ubuntu VPS / dedicated server hosting with Coolify                  | [Ubuntu / Coolify hosted deployment](./architecture/ubuntu-coolify-deployment.md)                      | [`ubuntu-coolify-deployment.svg`](./diagrams/generated/ubuntu-coolify-deployment.svg)                                                                                                                |
| See HTTP vs WebSocket traffic                                                  | [Service communication](./architecture/service-communication.md)                                       | [`service-communication.svg`](./diagrams/generated/service-communication.svg) and [`frontend-backend-map.svg`](./diagrams/generated/frontend-backend-map.svg)                                        |
| Review Better Auth modules, JWT/JWKS, and auth-service extensions              | [Service communication](./architecture/service-communication.md)                                       | [Generated auth runtime summary](./architecture/generated/auth-runtime.md) and [`auth-flow.svg`](./diagrams/generated/auth-flow.svg)                                                                 |
| Trace a user JWT from Better Auth into `records-service` and down to SurrealDB | [Generated auth runtime summary](./architecture/generated/auth-runtime.md)                             | [Generated records-service auth integration](./architecture/generated/records-service-auth-integration.md) and [`records-service-auth-flow.svg`](./diagrams/generated/records-service-auth-flow.svg) |
| Explain a grammar or mini-language with syntax-style branching                 | [Railroad diagrams guide](./guides/railroad-diagrams.md)                                               | Use fenced `railroad` blocks inside any docs page                                                                                                                                                    |
| Publish the docs externally                                                    | [Publishing the docs site](./guides/publishing-docs.md)                                                | `docker/Dockerfile.docs`                                                                                                                                                                             |
| Explore interactively and filter by app/service/package                        | [Interactive explorer](./explorer/index.html)                                                          | From `apps/docs-site/`, use `bun run dev` for local development or `bun run preview` for a production-style preview                                                                                  |

## Generated artifacts

Generated diagrams are written to `apps/docs-site/public/diagrams/generated/`:

| Diagram                                   | Mermaid source                                                                                                    | SVG                                                                                                               | PNG                                                                                                               |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Workspace dependency graph                | [`dependency-graph.mmd`](./diagrams/generated/dependency-graph.mmd)                                               | [`dependency-graph.svg`](./diagrams/generated/dependency-graph.svg)                                               | [`dependency-graph.png`](./diagrams/generated/dependency-graph.png)                                               |
| Service topology                          | [`service-topology.mmd`](./diagrams/generated/service-topology.mmd)                                               | [`service-topology.svg`](./diagrams/generated/service-topology.svg)                                               | [`service-topology.png`](./diagrams/generated/service-topology.png)                                               |
| Service communication                     | [`service-communication.mmd`](./diagrams/generated/service-communication.mmd)                                     | [`service-communication.svg`](./diagrams/generated/service-communication.svg)                                     | [`service-communication.png`](./diagrams/generated/service-communication.png)                                     |
| Frontend/backend map                      | [`frontend-backend-map.mmd`](./diagrams/generated/frontend-backend-map.mmd)                                       | [`frontend-backend-map.svg`](./diagrams/generated/frontend-backend-map.svg)                                       | [`frontend-backend-map.png`](./diagrams/generated/frontend-backend-map.png)                                       |
| Build + deploy order                      | [`deployment-order.mmd`](./diagrams/generated/deployment-order.mmd)                                               | [`deployment-order.svg`](./diagrams/generated/deployment-order.svg)                                               | [`deployment-order.png`](./diagrams/generated/deployment-order.png)                                               |
| Single-server Coolify deployment          | [`single-server-coolify-deployment.mmd`](./diagrams/generated/single-server-coolify-deployment.mmd)               | [`single-server-coolify-deployment.svg`](./diagrams/generated/single-server-coolify-deployment.svg)               | [`single-server-coolify-deployment.png`](./diagrams/generated/single-server-coolify-deployment.png)               |
| Multi-node Coolify + SurrealDB deployment | [`multi-node-coolify-surrealdb-deployment.mmd`](./diagrams/generated/multi-node-coolify-surrealdb-deployment.mmd) | [`multi-node-coolify-surrealdb-deployment.svg`](./diagrams/generated/multi-node-coolify-surrealdb-deployment.svg) | [`multi-node-coolify-surrealdb-deployment.png`](./diagrams/generated/multi-node-coolify-surrealdb-deployment.png) |
| Multi-node deployment flow                | [`multi-node-coolify-surrealdb-flow.mmd`](./diagrams/generated/multi-node-coolify-surrealdb-flow.mmd)             | [`multi-node-coolify-surrealdb-flow.svg`](./diagrams/generated/multi-node-coolify-surrealdb-flow.svg)             | [`multi-node-coolify-surrealdb-flow.png`](./diagrams/generated/multi-node-coolify-surrealdb-flow.png)             |
| Ubuntu / Coolify hosted deployment        | [`ubuntu-coolify-deployment.mmd`](./diagrams/generated/ubuntu-coolify-deployment.mmd)                             | [`ubuntu-coolify-deployment.svg`](./diagrams/generated/ubuntu-coolify-deployment.svg)                             | [`ubuntu-coolify-deployment.png`](./diagrams/generated/ubuntu-coolify-deployment.png)                             |
| Ubuntu / Coolify deployment flow          | [`ubuntu-coolify-deployment-flow.mmd`](./diagrams/generated/ubuntu-coolify-deployment-flow.mmd)                   | [`ubuntu-coolify-deployment-flow.svg`](./diagrams/generated/ubuntu-coolify-deployment-flow.svg)                   | [`ubuntu-coolify-deployment-flow.png`](./diagrams/generated/ubuntu-coolify-deployment-flow.png)                   |
| Auth flow                                 | [`auth-flow.mmd`](./diagrams/generated/auth-flow.mmd)                                                             | [`auth-flow.svg`](./diagrams/generated/auth-flow.svg)                                                             | [`auth-flow.png`](./diagrams/generated/auth-flow.png)                                                             |
| Forms-service auth flow                   | [`records-service-auth-flow.mmd`](./diagrams/generated/records-service-auth-flow.mmd)                             | [`records-service-auth-flow.svg`](./diagrams/generated/records-service-auth-flow.svg)                             | [`records-service-auth-flow.png`](./diagrams/generated/records-service-auth-flow.png)                             |

## Keeping docs fresh

From `apps/docs-site/`, generate or refresh all docs artifacts:

- `bun run generate`

Check whether generated outputs are current:

- `bun run generate:check`

Preview the docs locally with the same rsbuild app shell used in development and production:

- `bun run preview`

Build and publish the docs as a standalone container:

- follow [Publishing the docs site](./guides/publishing-docs.md)

Build the app-style docs frontend locally:

- `bun run build`

Run the app shell in development:

- `bun run dev`

## What is generated automatically?

The automation currently derives:

- internal workspace dependency graph
- Docker Compose deployment topology
- frontend-to-backend and service-to-service communication map
- deployment order and build order phases
- auth flow diagram
- auth runtime summary (Better Auth modules, JWT claims, and auth-service endpoint groups detected from the auth app)
- records-service auth integration summary (browser token handoff, records-service middleware, and Surreal `authenticate(token)` path)
- interactive graph data for the local explorer

## What is still curated by hand?

The prose in the markdown files stays human-readable on purpose. That lets the architecture docs explain _why_ the system is shaped this way, while the generated diagrams handle the constantly-changing graph details.

The Ubuntu / Coolify hosted deployment page is also intentionally curated: it is a reference operating model for production hosting, not something the repo can infer directly from source code alone.

The single-server and multi-node Coolify deployment pages are curated for the same reason: they are reference operating models grounded in official Coolify and SurrealDB deployment guidance rather than auto-derived from workspace metadata.

The current multi-node reference intentionally models Coolify's **multiple domains across multiple servers** pattern, where each workload server has its own proxy and public domain set.

Those curated deployment pages also now account for a self-hosted delivery plane built around Forgejo and a private OCI registry, because source control and artifact storage are part of the real deployment story too.

## Recommended maintenance rhythm

- Regenerate docs after adding or removing apps, services, packages, or Compose wiring.
- Regenerate docs after introducing a new service URL, WebSocket path, or auth integration pattern.
- Run `bun run generate:check` in CI or before merging architecture-heavy changes.