# Development guide

## Structure

- `cmd/drive` owns process startup and CLI dispatch.
- `internal/domain` contains dependency-free business rules.
- `internal/application` coordinates use cases through interfaces.
- `internal/adapters` implements PostgreSQL, storage, and external-service ports.
- `internal/transport` maps HTTP contracts to application calls.
- `internal/workers` executes persistent leased jobs.
- `web/src/features` owns frontend product features; `web/src/shared` contains reusable primitives.
- `api/openapi.yaml`, migrations, and sqlc queries are reviewed source contracts.

## Canonical checks

Native:

```text
go test ./cmd/... ./internal/...
npm --prefix web ci
npm --prefix web run check
```

Containerized:

```text
docker compose run --rm verify
docker compose up --build
```

## Contract workflow

Do not add an API handler before its OpenAPI operation exists. Do not write SQL directly in transport or application code; add a named sqlc query. Generated files are outputs and are never edited by hand. CI regenerates the PostgreSQL repository and rejects drift; the same check applies to the generated API client when it is introduced.

## Architectural changes

Create an ADR before changing storage semantics, public API conventions, package boundaries, deployment topology, or approved dependencies. An ADR records context, decision, consequences, and superseded decisions.