---
layer: as-is
status: implemented
code: [hal]
updated: 2026-08-23
decisions:
  - adr/0002-everything-is-a-module.md
  - adr/0010-applications-live-in-their-own-repository.md
  - adr/0017-modules-outside-the-core-are-grouped-by-domain.md
---

# 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](../../adr/0015-mesh-brokers-nodes-host-agents-think.md)).

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](../../adr/0015-mesh-brokers-nodes-host-agents-think.md)
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](../../adr/0017-modules-outside-the-core-are-grouped-by-domain.md), 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](../../adr/0010-applications-live-in-their-own-repository.md)), 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`](../../04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md)).
- 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.