Skip to content

Code generation

For: contributors who changed an API, a setting, a schema or a diagram. You’ll get: the command that regenerates each file, and the check that catches drift.

Generated files are never hand-edited. Each has a command that produces it, and where it’s committed, a *-verify target that fails CI on drift.

Committed

ArtifactFromRegenerateGate
api/openapi.yamlHuma operation definitionsmake openapimake openapi-verify
docs/reference/settings.mdthe settings registrymake config-docsmake config-docs-verify
docs/reference/make.mdthe Makefile + CI workflowsmake dev-docsmake dev-docs-verify
docs/reference/database.mdthe migrations + internal/platform/store/schemadoc/areas/make db-docsmake db-docs-verify
docs/design.md §2 mappackage doc comments + importsmake arch-docsmake arch-docs-verify
docs/diagrams/generated/*.svgD2 sourcesmake diagramsmake diagrams-verify
web/packages/design-system/generated/packages/design-system/src/tokensmake fe-tokensmake fe-tokens-verify
Visual baselinesPlaywright, pinned imageVisual baselines workflowmake fe-visual
e2e snapshotsPlaywright, pinned imageVisual baselines workflow (make e2e-update)make e2e

These are committed so a reviewer sees the effect in the diff — a renamed field shows up as a spec change in the same PR.

Not committed

ArtifactFromProduced by
web/packages/api/generated/api/openapi.yaml via orvalmake fe-codegen
web/apps/web/src/routeTree.gen.tsTanStack Router file routesmake fe-codegen
internal/platform/web/dist/Vitemake fe / make fe-build
web/apps/web/storybook-static/Storybookmake storybook-build

The orval client is gitignored because the spec is the source of truth — there’s nothing for it to drift against. That’s also why a fresh clone typechecks red until codegen has run.

Migrations

Goose migrations under internal/platform/store/migrations/{sqlite,postgres} are hand-written and applied at boot. Never edit an applied migration; add a new one.

Two long-lived branches will both take the next free number and goose silently skips the second. Check the highest number on main first.

Two things generation doesn’t give you

Names and types, not rules. The generated zod schemas give you wire field names; bounds, messages and trims stay hand-authored. Deriving the names is still what matters — a hand-mirrored schema once said maxAcquire where the wire says maxAcquisitions, so a user’s setting serialized into JSON the server ignored.

Trustworthy wiring, untrustworthy data. Generated MSW mocks emit optional fields as arrayElement([value, undefined]), so presence varies per call. Pass explicit overrides from the shared fixtures. What generation buys is the URL and method: a renamed route is fixed by regenerating, where a hand-written path would silently stop matching and its test keep passing.

.gitkeep

internal/platform/web/dist/.gitkeep is the one tracked file there. //go:embed all:dist won’t compile without the directory, and Vite’s emptyOutDir deletes it, so a build plugin rewrites it. Don’t tidy it away.