36 lines
2.4 KiB
Markdown
36 lines
2.4 KiB
Markdown
---
|
|
status: canonical
|
|
updated: 2026-11-16
|
|
---
|
|
|
|
# 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](glossary.md).
|
|
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.
|
|
|
|
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.
|