# System overview

Crown is a multi-application clinical audit platform built as a Bun/Turbo monorepo.

At a high level it is composed of:

- **frontend apps** built with Rsbuild and TypeScript
- **backend services** built mainly with Hono on Bun
- **shared packages** for auth, schema tooling, realtime, routing, and database abstractions
- **SurrealDB** as the primary operational database
- **Docker Compose** for local orchestration and deployment packaging
- **Traefik** for routed access in local and production deployments

## Platform layers

### Experience layer

User-facing applications include:

- `auth-ui`
- `audits`
- `application-list`
- `admin-ui`
- `schema-designer-v2`
- `nela-risk-calculator`
- `analytics-ui`

### Service layer

Key runtime services include:

- `auth-service`
- `records-service`
- `entity-service`
- `audit-service`
- `analytics-service`
- `user-activity-service`
- `cms-service`
- `support-service`
- `nela-service`
- `risk-score-service`

The ordinary Bun/Hono APIs can be deployed either as those logical services or
inside one `crown-core-api` process. The combined runtime preserves each
service hostname and route contract, so frontend deployments do not change.
NELA, risk scoring, AI, and ML training remain independent workloads.

### Shared platform layer

Shared packages provide the internal platform primitives:

- `@crown/realtime` for live updates and WebSocket helpers
- `@crown/router` for client navigation
- `@crown/db-adapter` for database schema abstractions
- `@crown/schema-*` packages for DSL, metadata, validation, and documentation
- `@crown/better-auth-*` packages for auth plugins and permission models
- `@crown/ui` for reusable interface components

## Core characteristics

- **Monorepo build orchestration** via Turbo
- **Runtime consistency** through Docker Compose
- **Direct service ownership** — apps retain service-specific URLs; in combined
  deployments those hostnames terminate at the `crown-core-api` dispatcher
- **Mixed protocols** — HTTP for standard request/response flows, WebSockets for live dashboards, notifications, locks, and content streams
- **Shared auth** — a central auth service issues tokens and publishes JWKS metadata for validation in other services

## Runtime topology

![Deployment topology](../diagrams/generated/service-topology.svg)

Source: [`service-topology.mmd`](../diagrams/generated/service-topology.mmd)

## Workspace dependency graph

![Workspace dependency graph](../diagrams/generated/dependency-graph.svg)

Source: [`dependency-graph.mmd`](../diagrams/generated/dependency-graph.mmd)

## How to read the architecture docs

- Use [deployment architecture](./deployment-architecture.md) when you care about containers, ports, startup order, or environment separation.
- Use [service communication](./service-communication.md) when you care about HTTP vs WebSocket flows and who calls whom.
- Use [database architecture](./database-architecture.md) when you care about SurrealDB, migrations, or schema generation.
- Use the [interactive explorer](../explorer/index.html) when the static graph becomes delightfully spaghetti-like.