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.6 KiB
layer, status, code, updated, decisions
| layer | status | code | updated | decisions | ||||
|---|---|---|---|---|---|---|---|---|
| as-is | implemented |
|
2026-08-23 |
|
The catalogue, and what its shape says
The catalogue holds 124 modules. Thirty-three belong to the mesh's own domain; the other ninety-one run on the mesh rather than being of it (ADR 0015).
The count is not the finding. The shape is.
How it is organised today
By namespace, and the namespace records origin rather than purpose:
- The mesh's own namespace holds the platform: the runtime and its daemons, the shared library, delivery, provisioning, configuration synchronisation, knowledge, identity, the board, developer tooling, and node presentation.
- A second namespace holds the work domain — tasks, workflows, agents, meetings — split across a handful of packages that share one schema.
- Everything else sits flat at the top level, one directory per piece of software.
What the flat level actually contains
Grouped by what they are for — a grouping the catalogue itself does not express:
| Purpose | Roughly |
|---|---|
| Data and storage services the mesh provisions against | Relational and document databases, a cache, an object store, a package registry, a time-series store |
| Messaging and identity | A message broker, an identity provider |
| Reachability | A VPN, a firewall, an intrusion filter, an SSH daemon, a resolver, a certificate authority, a reverse proxy, network equipment control |
| Forge and container plumbing | Forge integrations, an image registry, container lifecycle and retention |
| Media libraries | Acquisition, organisation, playback, transcoding, streaming |
| Workstation and desktop | Browser, file manager, monitors, session management, audio, package management, runtime managers |
| Hardware-specific support | Power and firmware control for particular hardware, filesystem management |
| Collaboration and productivity | File sync, office tooling, boards, automation, chat and messaging bridges, mail, analytics, dashboards, home automation, issue trackers and wikis |
| Third-party organisation integrations | Systems belonging to organisations outside the mesh |
Every row is several modules, and no row is a thing the mesh can see. Four modules together constitute "how a node is reachable", and they have no relationship the mesh can assign, version, reason about or replace as one unit. A change to how the mesh handles connectivity is made four times.
What the shape records
The catalogue's shape records what was installed, not what anything is for. One module is the unit of one piece of software, because that is the only granularity the module system offers.
This is the same failure ADR 0015 names for the platform core — boundaries drawn by deployment accident rather than by domain — appearing outside it, at four times the scale. The core is being recomposed; the flat level is addressed in principle by ADR 0017, which deliberately does not yet settle the domain list.
Two properties worth keeping
Whatever replaces the shape, two things about it are right.
Uniformity. A media server and the mesh's own coordinator are installed, provisioned, delivered and verified by identical machinery. The mesh's own components hold no privilege — which is what makes dogfooding structural rather than a discipline, and what makes moving a module out of the repository safe.
Placement is already decided. A standalone application belongs in its own repository (ADR 0010), and reviewers reject it in the monorepo. The catalogue's flat level is not a dumping ground by policy; it is one by history.
Known inconsistencies in the catalogue itself
Recorded because a reader will meet them:
- A documented requirement that every capability-exposing module declare the core runtime as a dependency is met by zero modules.
- A firewall-scoping key is declared by five manifests and read by none
(
04-ISSUES/003). - A connections block in the manifest is metadata: it describes a module's reachability and wires nothing.
- At least one module deliberately runs outside the standard per-module supervision, for reasons recorded in the operational memory. The standard path is not universal.