C4 Container Registry with Per-Container C3 Views

Use this pattern when a documentation site must expose C1, C2, and C3 without implying that a container is a component.

Semantic model

C1 System Context: the system, people, external systems, and principal relationships.
C2 Container view: deployable or runnable applications, services, stores, queues, and their relationships.
Container registry: an index of the C2 containers. A registry is navigation/information architecture, not a separate C4 level.
C3 Component view: the internal decomposition of exactly one selected container, plus the surrounding actors, systems, and containers needed to understand its relationships.

A container remains a container when opened at C3. The C3 page changes the level of detail, not the element type.

Unambiguous wording

Use:

# Web Application — Container

This page documents the **Web Application container** identified at C2. The diagram below is the container's **C3 Component view**: it opens that container to show its internal components and surroundings.

Use diagram titles of the form:

Web Application Container — C3 Component View

Avoid:

This C3 Component view opens the Web Application...
Containers (C3)
C3 Component registry

Those phrases can misclassify the container itself as a component or the registry as a C4 level.

For the adopted project:

Context (C1)
Overview (C2)
Container Registry (C3 views)
  Web Application
  API Service
  Documentation Site
Requirements - Functional
  Registry
  <FR-ID>
Requirements - Non-Functional
  Registry
  <NFR-ID>

The registry page should say it lists C2 containers and links to a C3 Component view for each container.

C3 page contract

Each container entry should include:

a heading that explicitly identifies the subject as a container;
an introduction distinguishing the C2 subject from the C3 view;
an editable Draw.io diagram with the container boundary, internal components, and surroundings;
source-observed components separated from target/unimplemented components;
relationship edges supported by source or approved target design;
explicit treatment of adjacent elements with no observed relationship instead of inventing an edge;
source evidence and non-deployment/non-acceptance caveats where applicable.

Shared compiled packages are components/libraries inside consuming deployables, not extra container rows, unless they have an independently deployable runtime boundary.

Source-default versus deployed-runtime reconciliation

Track two immutable baselines independently:

current repository source — the application default SHA used to classify implemented internals;
deployed runtime — the application/image and GitOps SHAs used to describe what users can currently execute.

A source merge can make a C3 page stale before deployment. If a page still anchors source-observed internals to an older commit and labels newly merged components as target/unimplemented, content completeness is partially in sync even when C1 deployment wording remains accurate. Inspect implementation PR changed files and distinctive exported symbols rather than relying only on a Delivery summary. Then update the container page and its editable Draw.io source together so both distinguish current source, deployed runtime, and remaining target design.

When closing a prior partial verdict after its remediation PR merges, verify all three conditions:

reviewed-head ancestry and exact-default CI are current;
later documentation changes preserve the corrected Architecture contract;
no newer application or deployment SHA changes the source/target classification or relationships in C2/C3.

If the required Draw.io governance skill cannot be loaded, do not patch prose alone. Preserve the accurate C1/runtime checkpoint, identify the stale C3 source anchor and newly implemented components, and defer one coordinated prose-plus-diagram correction.

Fail-closed validation

Validators should require:

canonical C1 and C2 routes and labels;
registry language identifying C2 containers and per-container C3 views;
<name> — Container page headings;
<name> Container — C3 Component View diagram titles;
rejection of ambiguous legacy wording;
native editable Draw.io sources;
component boundary membership and exact relationship endpoints;
no invented cross-container calls;
source-observed versus target separation.

Mutation-test the validator by temporarily restoring an ambiguous phrase or reversing/removing a required edge and requiring a non-zero result.

Publication verification

Run the repository's full validator/test/typecheck/build set, visually inspect the registry and each C3 page, obtain independent fail-closed review, then publish through an exact-head PR/CI/merge/integrated-CI sequence. Protected Pages redirects must be reported as an authentication boundary rather than treated as deployed article evidence.

5.0 KiB Raw Blame History