Skip to content

ADR-0016: Architecture meta-model and machine-readable 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.

  • Status: Accepted 2026-10-09 by the product owner (decisions D22–D26)
  • Date: 2026-10-09
  • Deciders: Dmitry Khaymov (product owner); proposed by the 2026-10 design plan
  • Tags: meta-model, documentation, platforms, planes

Context

The site described the Factory twice: a June-2026 twelve-platform structure with 156 named services, and an October-2026 nine-plane structure. The user decided that both are valid and must coexist, that every logical microservice is to be designed in full, and that catalogs for ~180 services cannot be kept consistent by hand.

Decision

  1. Hierarchy: Plane → Platform → Bounded Context → Logical microservice → design facets (aggregates, entities, tables, APIs, messages, workers, grains, sagas, options, metrics, security, dependencies, failure modes, NFR class, deployment). Planes are logical layers; platforms are product/delivery groupings inside planes; 16 platforms exist (12 former + Model & Compute, Tools & MCP, Data & Event, Product Fleet Operations); bounded contexts BC-01…BC-33 keep the ownership map's ids and writers, BC-34…BC-42 are added.
  2. Granularity instead of deletion: every former catalog row stays a logical service with a deployment granularity of standalone, module-of-host, external-canonical or later; the former disposition is kept as provenance.
  3. Two sources, one truth each: facts live in model/**/*.yaml (JSON-Schema validated); narrative lives in hand-written pages with a fixed section skeleton that includes generated fragments. The generator runs inside mkdocs build and as a CLI; generated output is committed; model errors fail the build.
  4. Canonical anchors: each entity has exactly one anchor with a reserved prefix; hand pages link, never redefine.
  5. Page set per platform: eight generated catalog pages and seven hand-written narrative pages; plane indexes include six generated sections.

Consequences

  • Positive: one consistent catalog across ~180 services and all cross-cutting entities; no duplicate authority; reviewable diffs of generated pages in pull requests; the model is reusable for later tooling (C4, OpenAPI stubs) without re-authoring.
  • Negative: authors must learn the YAML entity schema; generated pages must not be edited by hand (the first line says so and the manifest detects it); build time grows with the site.
  • Neutral: the June-2026 catalog content is archived under archive/catalogs-2026-06/ as provenance and seed.

Alternatives considered

Alternative Why not chosen
Hand-written catalogs only Already drifted across 145 pages; cannot keep 180 services and their events consistent
Replace the twelve platforms with planes only The user chose coexistence; platforms carry the product and delivery view
Reduce the service list to the 34 modules Contradicts the direction to design every microservice in detail