Development Setup

Development Setup

This page covers building, testing, and linting a working tree. To bring the stack up and make a request first, see Getting Started.

Bring up the stack

./scripts/dev-start.sh

The one-command bootstrap starts the backing services, applies the schema and seed, and prints the per-service run commands. Getting Started walks through the details.

Build, test, lint

Command	Purpose
make build-all	Build the Go services and the UI. Go binaries land in dist/bin/<service>/.
make test-all	Run go test -race -count=1 for every Go module plus the UI tests.
npm run check:all	Run the full pre-commit lint suite — i18n parity, design tokens, terminology, duplicate JSON keys, timezones, architecture-doc triggers, and migration timestamps. CI runs the same set.
npm run db:migrate	Create a new database migration.

The Go workspace

The Go modules share a go.work workspace at the repository root. Each module references its sibling packages, and go.work is what resolves those references to the local source tree. A fresh git clone already includes go.work, so go build from inside the repository just works.

The one consequence to know: if go.work is missing from a build context — for example a Docker build that copies only one service's directory — Go falls back to fetching the modules from their remote path instead of using your local source, and the build silently uses a stale snapshot. Docker builds must copy go.work and every package the service depends on; CI must use a full checkout.

Conventions

Code style and micro-decisions live in conventions.md. Operational debugging — service logs, the admin-API helper, body-level debug logging — is in local-dev-debugging.md.

See also

• Getting Started — first bring-up and request.
• Contributing — the change workflow and pre-commit checks.
• Architecture Internals — the design documentation to read before editing.