# 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:

```md
# 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:

```text
Web Application Container — C3 Component View
```

Avoid:

```text
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.

## Navigation pattern

For the adopted project:

```text
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:

1. a heading that explicitly identifies the subject as a container;
2. an introduction distinguishing the C2 subject from the C3 view;
3. an editable Draw.io diagram with the container boundary, internal components, and surroundings;
4. source-observed components separated from target/unimplemented components;
5. relationship edges supported by source or approved target design;
6. explicit treatment of adjacent elements with no observed relationship instead of inventing an edge;
7. 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:

1. reviewed-head ancestry and exact-default CI are current;
2. later documentation changes preserve the corrected Architecture contract;
3. 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.