jschoubben
143f8ab2f1
The domain-grouping premise is testable, so it was tested before drawing a list. Co-change across the full history of the module catalogue, current modules only, platform namespace excluded. Nine commits in ten touch exactly one module, and 50 of 89 modules have never been edited alongside anything. Two clusters exist above that floor. Reachability holds up: proxy, resolver, firewall and VPN genuinely move together under one intent, three times in recent history. That is the shape ADR 0017 describes and the only place the measurement finds it. The provider cluster does not, and this is the finding worth having. Every multi-provider commit is a cross-cutting manifest change applied N times — feature detection, hook conventions, volume binds, network scoping. None is a change to what a database is. Merging them would not have prevented one of those commits, and the history already shows the fix that worked: verify by shape in the SDK rather than copying a script into every module. Move the concern into the machinery, do not merge the modules carrying it. ADR 0017 keeps its principle and gains a pointer to this narrowing.
5.2 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. That effort is
01-RESEARCH/005-domain-grouping, and its
first measurement already narrows this record's scope: co-change analysis supports grouping for
reachability, argues against it for the provisioned infrastructure providers, and finds no
signal either way for the fifty modules that never change alongside anything.
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.
03-DESIGN/00-as-is/10-module-catalogue.md— the catalogue's current shape, which is the evidence for the problem.