feat: mine reusable AeroSim channel lessons

2026-09-10 11:41:25 +00:00
parent fad0703294
commit 31088a5ed8
11 changed files with 670 additions and 2 deletions
@@ -0,0 +1,110 @@
+# 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.