hq/02-DECISIONS/0048-the-substrate-is-named.md

status, date, deciders, reconstructed, extends

status	date	deciders	reconstructed	extends
accepted	2026-08-27	jochen	false	0030-the-repository-structure.md

48. The substrate is named

Context

The substrate is defined by a test — what the control plane consumes and cannot grant itself — and the design layer describes its members entirely by role: a relational store, a message bus, an object store, an image registry.

No design document names a product. Postgres appears in zero of them. The names occur only in the as-is layer and in research, describing what already runs.

That is a gap rather than a discipline. The rule it came from — 01-RESEARCH's research never identifies the mesh it observed — is about node names and domains, not about software. Nothing is protected by declining to write Postgres in a public repository, and something is lost: a design that never names a product does not record that the choice was made.

Two costs, both already accrued:

• substrate.lock cannot be written from the design. It pins images by digest, and a digest belongs to a named image.
• A reader cannot tell a settled choice from an unexamined one. "A relational store" reads the same whether the store was chosen deliberately or never considered.

Decision

The substrate is named, and the names are these:

Role	Product	Why
relational store	PostgreSQL	In use, understood, and the provisioning model already assumes its notions of database, role and schema.
message bus	LavinMQ	In use, speaks AMQP, which is what ADR 0001 assumes. Interchangeable with other AMQP brokers at the protocol level, which is what makes it a safe choice rather than a locked-in one.
object store	MinIO	In use, speaks the S3 protocol, which is the closest thing to a portable object-store interface.
image registry	the OCI distribution registry	In use, and the format is the standard rather than a vendor's.
container runtime	Docker	In use. Podman is the plausible alternative and was not chosen for any deficiency — Docker is what the machines run today and what the current tooling assumes.

Outside the substrate

The gap is not only the substrate's. The design layer names roles for these too, and the same correction applies — a role is a legitimate abstraction, but the product belongs beside it:

Role, as the design says it	Product	Tier
the forge	Gitea	a hosted workload — the mesh builds from it but does not need it to run
the coordinator	the mesh's own pipeline	tier 2 — part of the control plane, not a product
ingress — exposure, certificates	Traefik	see below

Ingress is a real gap rather than a naming one, and this record does not close it. The connectivity context lists exposure and certificates among its responsibilities, and no design document says what terminates TLS, how a route reaches a container, or which tier that belongs to. Traefik is what does it today. Whether it is substrate turns on the same test — can the control plane grant itself a route? — and nobody has applied the test. Named here so the gap is visible; left open because naming it is not answering it.

Identity is deliberately absent. Whether an identity provider is substrate at all depends on whether the control plane delegates authentication, which is undecided (07-the-substrate.md). Naming a product before deciding whether the role exists would be the mistake this record is correcting, in reverse.

The role and the product are both written. A design says the relational store (PostgreSQL) rather than one or the other. The role is what the argument turns on; the product is what gets installed, and a reader needs both.

Consequences

• substrate.lock becomes writable. It pins named images by digest, which was impossible while the design refused to say which images.
• Continuity is the argument, and it is a real one. Every choice here is what already runs. Nothing was re-litigated, because nothing about the new shape gives a reason to — and changing a substrate service is a migration of the mesh's own state, which is not a cost to pay for novelty.
• Protocols, not products, are what the design depends on. The bus is reached over AMQP, the object store over S3, the registry over the OCI protocol. Replacing a product is then a substrate migration rather than a redesign — which is the property that makes naming them safe rather than a commitment that cannot be revisited.
• The relational store is the exception, and it should be said. The provisioning model uses databases, roles and schemas as Postgres means them, and ADR 0044 already records that two stores from different vendors are not substitutable for a consumer. Replacing it is not a swap.
• The rule that caused this is narrowed, not repealed. Research still does not identify the mesh it observed — node names, domains, addresses. Product names were never in scope, and the over-application cost the design layer its concreteness.

References

• 07-the-substrate.md — the test these satisfy.
• ADR 0001 — why the bus speaks AMQP.
• ADR 0046 — pinning by digest, which needs a name.
• ADR 0044 — why the store is the one that cannot simply be swapped.