Requirements Decide the Topology

The non-functional requirement dictates the system's topology, regardless of any disagreements regarding design preferences. Anton, a software engineer, explains that when requirements become contract, the contract then translates to tasks and specs, the design argument hinges on the precise condition laid out in the requirements, not on personal taste or seniority.

The requirement specifies that reads and writes operate under distinct conditions - different volumes, shapes, failure modes. This distinction results in two layers interacting with the database; one for reads, another for writes. No other components intervene, eliminating the need for auxiliary services like store, writer, DAO, or service.

The layout of the code mirrors this separation - component type dictates package structure. For instance, repository reads and manager writes, with handlers and grpc entities located within.

Numbers reflect this structure: as of 2026-08-16, there are 2,733 .go files, 252 packages, each with an average length of 39 lines. The layout benefits from separating code by component type first, producing smaller files inherently, rather than asking teams to write shorter code.

The cost of this layout is evident in the extra package layers. Managers must traverse a repository to read data, adding an extra step to each feature, but this provides a clear line of sight into how reads and writes can be modified, measured, and reasoned about separately.

Two systems emerge from this requirement: one where heavy background work is synchronous, another where it's asynchronous through a queue. Tenant isolation and data volume must be managed through a bitemporal model, separate from simple UPDATE operations.

This is not about a fully functional system but rather a breakdown of structure and its cost, not a report on an existing setup. The design decision is based on requirements, not personal preference or default practice.