The shape of the code
The layers, what may import what, the linters that hold the line, and where tests live.
Komrad’s Go code is arranged in layers. Because much of the code is authored by AI agents, who tend to (coughs loudly) not always write the cleanest code, Komrad has a series of strict linters that enforce this structure. Depguard enforces the arrows in the diagram.
The layers#

Linters#
Most of this structure is enforced via linters. The panel can’t import tmux or the store, for example, and services can import generated protos. Code that crosses one of these lines fails lint.
Any custom linters live in a plugin under tools/komradlint, which enforces structure further.
For instance, every sentinel error comes from a fail constructor that names its kind, so the declaration also decides the RPC code, and handlers have to be a single call, to keep business logic in services.
Tests#
Tests have rules too. Unit tests can’t run git directly, for instance; they have to respect the fake git used for tests.
Komrad tests each behaviour at the lowest layer that can see it.
| Layer | Runs against | Owns |
|---|---|---|
| Store | real Postgres | queries and ordering |
| Service | the real store, with fakes | the rules |
| Adapter | a fake service | validation and error codes |
| Scenario | everything real | a feature from end to end |
| Panel | the frame and the requests | keys, screens and forms |