komrad

The shape of the code

The layers, what may import what, the linters that hold the line, and where tests live.

Edit on GitHub

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#

The cli starts the server, which passes each request to the rpc and mcp handlers, which call the services. Services reach Postgres through the store and the outside world through the git, tmux, harness and forge adapters. The ui is a client that talks to the server over Connect only.

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.

LayerRuns againstOwns
Storereal Postgresqueries and ordering
Servicethe real store, with fakesthe rules
Adaptera fake servicevalidation and error codes
Scenarioeverything reala feature from end to end
Panelthe frame and the requestskeys, screens and forms