newdrive/docs/development.md

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:

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

Containerized:

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.