How we organise an API
Our APIs are modular monoliths: one deployable service, split inside into feature
Simplified hexagonal rules
The exact rules we keep from hexagonal architecture, the ones we dropped, and why each
Module layout
The folder tree of an API and of one module, what goes in each folder, and how files are
Between modules
How one module uses another: a direct call to its public functions for a question, an
Errors, validation and config
Where input is checked, how failures travel from a use-case to an HTTP status, and how
Tests and migrations
How we test an API (real Postgres, fakes only at the edge) and how schema changes are
Code mistakes
Structure problems we found when we reviewed our own APIs in October 2026. Each one cost