jschoubben
702efca6bb
HQ held only the to-be. Every reader had to already know the system the decisions were about, and an as-is claim had nowhere to live except inside an intention. Adds 02-DESIGN/00-as-is — eleven documents written from the implementation and the operational record, not from intent, including the parts nobody would choose again. The two existing designs move under 01-to-be. Layers are declared in frontmatter and never mix: a design that ships does not move, its as-is counterpart is written, and both stand. Back-fills adr/0001-0014 for decisions taken in implementation and never recorded — the broker, the module abstraction, the mesh database, managed files, provisioning, migrations, the workspace removal, failing loudly, the constitution, application placement, linking, the employee model, the artifact, the three silos. Each marked reconstructed, dated from the history, and citing the evidence it was recovered from. The two existing records renumber to 0015 and 0016 so the ledger runs oldest first; 0017 extends 0015 to modules outside the core, principle only — the domain list is deliberately not invented here. how-we-build.md becomes the source of the mesh constitution, with a sync playbook, so the enforced copy stops being the only one that is true. Process becomes explicit: five playbooks, eight thin skills that defer to them, a repository map, and AGENTS.md with CLAUDE.md as its include. The five Observations become 04-ISSUES 001-005 where they can be owned and closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge base. That claim is what decision 27 rests on, it was never checked, and the README now says so instead of repeating it. Also corrects the ADR index into something generated, the "02-DESIGN is empty" claim, the VISION.md pointer that did not survive the repo split, and a note asserting the symlink rule was contradicted — it was a misreading; the rule forbids hand-made links, the installer links by design.
4.8 KiB
status, date, deciders, reconstructed, extends
| status | date | deciders | reconstructed | extends |
|---|---|---|---|---|
| proposed | 2026-08-23 | jochen | false | 0015-mesh-brokers-nodes-host-agents-think.md |
17. Modules outside the platform core are grouped by domain, not by single function
Context
ADR 0015 recomposes the platform's own modules into bounded contexts named after their aggregates, and sends the rest out of the monorepo on the grounds that they run on the mesh rather than being of it.
That leaves the larger half unaddressed. Around three quarters of the catalogue are modules that are neither part of the mesh's domain nor standalone applications: a firewall, a VPN, an SSH daemon and a resolver; a file manager, a media player and a system monitor; a set of media-library services. Today each is its own module, because one module is the unit of one piece of software, and no other grouping exists.
The result is that the catalogue's shape records what was installed, not what anything is for. Four modules that together constitute "how a node is reachable" have no relationship the mesh can see: they cannot be assigned, versioned, reasoned about or replaced as one thing, and a change to how the mesh handles connectivity has to be made four times.
This is the same failure ADR 0015 names for the core — boundaries drawn by deployment accident rather than by domain — appearing outside it.
Considered options
- Leave them as they are. Rejected. The core gets domain boundaries and everything else keeps accident boundaries, so the catalogue becomes harder to read after the refactor than before it.
- One module per piece of software, with a tag or category field. Rejected. A label is not a boundary: it does not change what can be assigned, versioned or replaced as a unit, and it drifts from the thing it labels.
- Group them into domain modules, each owning the software that serves one purpose. Proposed here.
- Extend ADR 0015's contexts to cover everything. Rejected. Those contexts are named for the mesh's own aggregates; a media library is not an aggregate of the mesh, and forcing it into that model repeats the metaphor-naming mistake ADR 0015 exists to correct.
Decision
Proposed — the principle is settled; the domain list is not. See "Open" below.
Modules that are not part of the platform core are grouped into domain modules. A domain is named for the concern it serves, and owns the software that serves it. The unit stops being one piece of software and becomes one purpose.
This extends ADR 0015 rather than replacing it. The eight bounded contexts for the mesh's own domain stand unchanged. This decision covers what ADR 0015 leaves outside them.
Naming follows the same rule as the core: name the domain for what it does, not for what it is made of. Connectivity, not a VPN implementation.
Consequences
- A domain becomes assignable, versionable and replaceable as one thing. Changing how nodes reach each other is a change to one module.
- The catalogue's shape starts describing purpose. A reader can tell what a mesh is for from its module list.
- Swapping an implementation stops being a module replacement, with the data-volume and provisioning consequences that carries, and becomes a change inside a domain.
- The count drops sharply, which is a symptom of the improvement rather than the point of it.
- Grouping conceals. A domain module hides which implementation is in use, and every operational question — which port, which unit, which credential — gains an indirection.
- The migration is not free and has no obvious increments: a domain is only useful once everything belonging to it has moved.
- Some modules genuinely serve one purpose and are already correctly sized. Grouping for its own sake would be the same error in the other direction.
Open
The domain list is not settled and this record does not invent one. What is decided is the principle; what is not decided is the set. Candidate groupings are visible in the catalogue — connectivity and reachability, node presentation and desktop, media libraries, observation and metrics, storage and data services — but naming them here would be reconstructing a decision that has not been taken.
Settling the list is a research effort, not an act of this record. Until it concludes, this
ADR stays proposed.
References
- ADR 0015 — the core decomposition this extends, and its rule about naming a context after its aggregate.
- ADR 0010 — standalone applications are already out of scope here; they are not domains and do not group.
02-DESIGN/00-as-is/10-module-catalogue.md— the catalogue's current shape, which is the evidence for the problem.