# 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 forms-service auth integration](./architecture/generated/forms-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 `forms-service` and down to SurrealDB | [Generated auth runtime summary](./architecture/generated/auth-runtime.md) | [Generated forms-service auth integration](./architecture/generated/forms-service-auth-integration.md) and [`forms-service-auth-flow.svg`](./diagrams/generated/forms-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 | [`forms-service-auth-flow.mmd`](./diagrams/generated/forms-service-auth-flow.mmd) | [`forms-service-auth-flow.svg`](./diagrams/generated/forms-service-auth-flow.svg) | [`forms-service-auth-flow.png`](./diagrams/generated/forms-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)
- forms-service auth integration summary (browser token handoff, forms-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.