Architecture meta-model¶

Decision

This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.

Decided on 2026-10-09 (ADR-0016; decisions D22–D26). This page is the vocabulary every other architecture page uses.

The hierarchy¶

flowchart TB
    PL["Plane (9)<br/>logical responsibility layer"] --> PF["Platform (16)<br/>product / delivery grouping inside a plane"]
    PF --> BC["Bounded context (BC-nn)<br/>one authoritative writer per state"]
    BC --> SVC["Logical microservice<br/>deployment granularity: standalone · module-of-host · external-canonical · later"]
    SVC --> AGG["Aggregates → entities / value objects → DDL tables"]
    SVC --> API["APIs: REST (public, BFF) · gRPC (internal, code-first)"]
    SVC --> MSG["Messages: events (topic context.area.vN.name) · commands · consumed events"]
    SVC --> RUN["Workers / jobs · grains · sagas"]
    SVC --> OPS["Options · metrics · security · dependencies · failure modes · NFR class · deployment"]
    X["Cross-cutting entities: agents · skills · tools · model profiles · workflows · templates · libraries · descriptors / DSLs · gateways · stores · topologies · NFR classes · externals · components · traceability"] -.-> SVC

Hold "Alt" / "Option" to enable pan & zoom

Level	Meaning	Owns	Does not own
Plane	A logical boundary that names what must be owned, decided and observed. The nine planes come from the October-2026 target architecture.	Its platforms; a plane index page with generated sections	Deployables, teams, budgets
Platform	A product or delivery grouping inside one plane: the twelve June-2026 platforms plus four added on 2026-10-09. A platform has one default host for its modules and a documentation page set.	Bounded contexts; a page set of 8 generated catalogs and 7 hand-written narrative pages	State (that belongs to contexts)
Bounded context	A DDD boundary with exactly one authoritative writer per state; ids BC-01…BC-33 come from the ownership map, BC-34…BC-42 from the design plan. Its slug is the first segment of every topic its services publish.	Aggregates and their invariants; the services that implement them	Another context's state (reads go through APIs or events)
Logical microservice	The unit of design: one page, one model entry. Granularity says how it ships at first (decision D23).	Aggregates, tables, APIs, messages, workers, grains, sagas, options, metrics, security, dependencies, failure modes	A deployment unit of its own unless `standalone`

Deployment granularity¶

Value	Meaning	Design obligation
`standalone`	A host: its own process, database connection and pipeline. Sixteen exist, one per platform (for example `ControlPlaneApi`, `AgentRuntimeWorker`).	Full page; deployment, ports, replicas, topologies
`module-of-host`	A module inside a host; same process and database, separate schema ownership and namespace. Extraction into a host needs a documented trigger, owner, migration, event compatibility, authorization changes and rollback.	Full page; `host` named; no own pipeline
`external-canonical`	Provided by a ConnectSoft foundation, template or external system of record (Identity Platform, Config Platform, SaaS templates, Azure DevOps, OpenTelemetry backends). The Factory integrates, it does not own.	Page describes the integration contract and the `external_ref`; no aggregates or tables of its own
`later`	A named target outside early scope.	Page states the trigger that brings it into scope

The former catalog disposition (module, merge, external, conditional, defer) is kept on every registry row as provenance; it maps to granularity as module and merge → module-of-host, external → external-canonical, conditional → standalone, defer → later.

Statuses¶

Pages carry doc_status: target (design intent), current (what exists at the recorded revisions), decision (an ADR or recorded choice), evidence (verified facts with a date), historical (kept for provenance). Model entities carry status target / current / evidence; a registry service without a model file renders as unmodelled in every catalog so that links never break.

Where things are written¶

Artefact	Source of truth	Rendered where
Facts about a service (fields, tables, endpoints, events, workers, options, metrics, security, dependencies, failure modes, NFR class, deployment)	`model/services/<platform>/<ServiceId>.yaml`	The eight generated catalog pages of its platform, the global catalogs, and the fragment sections included by its design page
Narrative about a service (purpose, boundaries, reasoning, examples, current implementation, later capabilities)	`<platform docs_dir>/services/<slug>/index.md` (hand-written, scaffolded once)	Itself
Platform narrative	`overview, workflows, ui, security, observability, deployment, later-capabilities` pages (hand-written)	Themselves, with generated summary fragments
Plane narrative	`planes/<plane>/index.md` and its hand pages	With six generated sections (platforms, contexts, services, boundary events, gateways, coverage)
Cross-cutting entities	`model/*.yaml`, `model/agents`, `model/tools`, `model/skills`, `model/workflows`	`architecture/catalogs/*`
Requirements	`model/traceability/{fr,fux,nfr,xl}.yaml`	`architecture/traceability/*` and the coverage page
Decisions	`architecture/adr/*`	ADR index

The generator (tools/docs_model) validates the model on every mkdocs build: unknown references, two producers of one event, a topic whose context segment is not the producer's context slug, a table without a tenant column, a tool whose side-effect class exceeds the agent's policy, or an approval-free shared-write tool all fail the build. The rules are listed on the model report page's companion, the documentation standards.

Identifiers and anchors¶

Service ids are PascalCase (RunControlService); slugs are derived (run-control-service), never authored.
Every entity has exactly one canonical anchor: svc-<slug> on its platform's microservices page, bc-<slug> on bounded contexts, evt-<context-slug>-<event-slug> on events, agg-<service-slug>-<name> on aggregate roots, tbl-<service-slug>-<table> on the DDL appendix, pf-<slug>, pl-<plane>, agent-<id>, tool-<id>, prof-<id>, tpl-<id>, lib-<id>, dsl-<id>, gw-<id>, store-<id>, fr-<id> and so on.
Hand pages link to anchors, never redefine them; a per-platform link file (includes/generated/links/<platform>.md) offers reference-style definitions.

Platform map · Ownership map · Services catalog · Model report
ADR-0016 · Documentation standards