# Local development

This guide complements the root `DEPLOYMENT.md` and focuses on the local developer workflow for the monorepo docs and architecture model.

## Local stack model

Local development usually runs with:

- Docker Compose for infrastructure and deploy-like stacks
- Bun + Turbo for workspace commands
- optional Traefik routing for `.localhost` domains

## Typical workflows

### Build the workspace

- `bun run build`

### Start local application stacks

Use the existing compose workflows documented in the root deployment guide.

### Refresh architecture docs

From `apps/docs-site/`, run:

- `bun run generate`

### Preview the docs app

- `bun run dev`

Then open:

- `http://localhost:4317/`
- `http://localhost:4317/explorer/`

## When to regenerate docs

Regenerate the docs whenever you change:

- workspace dependencies in `package.json`
- Docker Compose service topology
- frontend service URL mappings
- WebSocket usage patterns
- deployment order or startup dependencies

## Recommended habit

A good lightweight habit is:

1. make the architecture change
2. from `apps/docs-site/`, run `bun run generate`
3. inspect the docs app, explorer, or generated SVGs
4. commit the updated docs artifacts alongside the code change

That keeps the diagrams from drifting into speculative fiction — which is fun in novels, less so in incident response.