111 lines
5.0 KiB
Markdown
111 lines
5.0 KiB
Markdown
# 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.
|