37 lines
1.4 KiB
Markdown
37 lines
1.4 KiB
Markdown
# 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.
|