Docs README

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
• System overview
• Deployment architecture
• Single-server Coolify deployment
• Multi-node Coolify + SurrealDB deployment
• Ubuntu / Coolify hosted deployment
• Service communication
• Generated auth runtime summary
• Generated records-service auth integration
• Database architecture
• Local development guide
• Publishing the docs site
• Railroad diagrams guide
• Adding a service
• Adding a package
• Interactive explorer

Choose the right page

Generated artifacts

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

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

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.