Files
hq/00-META/principles.md
T
jschoubben 9f08a430aa Principles: logic belongs to one module, named by its seat; the least code in shared packages
The operator, 2026-11-22: "it's better to let module A use module B's tool than both using a shared sdk function"; "logic should belong to a specific module, defined by its contract (seat)"; and at 21:02: "since seats can have multiple (applicable) occupant modules, the seat contract is generic, but the occupant module can have vendor-specific tools on top of the seat tools".
2026-11-22 21:00:21 +01:00

4.0 KiB

status, updated
status updated
canonical 2026-11-22

The principles

A short, living list. Every question met while building is tested against these principles and answered by the lead in one line; only a question no principle settles goes to the operator or to a decision record. A detail that a principle settles is not written down as a design line or a record. The list changes when the operator says so: add, sharpen or drop a principle in a pull request to this file.

  1. NATS-native. Every interaction between modules is an event, or a call over the bus where an answer is needed. A module keeps its data in the bus's own storage, and reads another module's data only by asking it, through its verbs or its tools.
  2. The mesh owns the truth. State lives in the mesh and is written onto the nodes from there. Nothing is changed by hand on a node.
  3. Failure is loud. Nothing reports success when it did nothing, and nothing fails silently. When in doubt, fail.
  4. A module is steered by its tools. Everything a module holds can be read, everything it does can be started by hand, and everything that goes wrong can be recovered, all through its tools.
  5. Everything ships the same way. The mesh's own parts go through the same build, check and delivery as any app.
  6. Nothing is exposed publicly. No data leaves the mesh unasked: no secret in a record, a log or a public repository, no service reachable from outside unless it is meant to be. Inside the mesh, every agent and module is trusted; who may do what is not a question to ask.
  7. No part without a need. Every mechanism, field, seat and step exists because something needs it; prefer what exists over a new one, and remove what no longer serves. Never a shortcut instead of the right shape.
  8. One word per thing, from the glossary.
  9. Depend on the contract, at the level it is interchangeable. A module depends on a seat where the mesh means more than one module to be able to fill the need, and on a module where only that module does; never on another module's internals.
  10. The module is the unit. Everything is done per module, never per repository. A repository is only where a module's files are kept; a merge moves only the modules it changes.
  11. Configurable, never hard-coded. A value that can differ between machines, modules or over time (a port, a path, a bound, a cap, a name, a time) is a setting with a default, never written into the code.
  12. A module writes only its own. A module writes its own files and state alone; what another module needs from it goes through a provision or a contribution that module declares, never a file written in its place.
  13. Logic belongs to one module, named by its seat. What a module does lives in that module, named by the seat it holds, whose verbs are its contract. Another module that needs it calls the seat's verbs where the need is interchangeable between the seat's holders, and the holding module's own tool only where that module alone fills the need (a holder may serve tools of its own beside the seat's verbs); never a shared function both import. mesh-sdk, the domain SDKs and the contracts modules hold the least code possible: every change to a package is published before any module can use it, and every importer is then rebuilt. A function moves into a shared package only when it is a seat's contract itself: its records, keys and events, and the client package of its verbs.

The operator, 2026-11-22: "it's better to let module A use module B's tool than both using a shared sdk function"; "logic should belong to a specific module, defined by its contract (seat)"; and at 21:02: "since seats can have multiple (applicable) occupant modules, the seat contract is generic, but the occupant module can have vendor-specific tools on top of the seat tools".

How it is checked: the one code review of a milestone checks the code against these principles and the design's shape; an answer to a develop question names the principle that settles it.