# Adding a service

Use this checklist when introducing a new backend service to Crown.

## Minimum implementation checklist

- create the new workspace app under `apps/`
- add its `package.json`
- add its runtime entrypoint and routes
- add a `Dockerfile`
- add the service to `docker-compose.yml`
- add any production/E2E overrides if needed
- expose the right frontend URL variables for any UI that consumes it
- add auth / JWKS configuration if the service is protected
- wire database credentials if it talks to SurrealDB

## Make the docs pipeline pick it up

The generators are designed to discover most of the above automatically, but they rely on a few conventions:

### Naming conventions

Prefer service names that match the current platform conventions:

- compose runtime names like `something-service`
- environment variables like `SOMETHING_SERVICE_URL`
- frontend build-time variables like `SOMETHING_SERVICE_EXTERNAL_URL`

### Source patterns the generators understand

The communication map looks for patterns such as:

- `hc<...>(SERVICE_URL, ...)`
- `createAuthClient(...)`
- `new WebSocket(...)`
- known service URL env names in source and build config

If you follow those conventions, the diagrams should update with little or no extra work.

## After adding the service

Run:

- from `apps/docs-site/`, run `bun run generate`

Then verify:

- the service appears in the deployment topology
- the deploy-order graph includes it in the right phase
- frontend/service communication edges appear where expected
- the explorer can find the new node