docs(corpus): add architecture-container template - #1529
Conversation
tucktuck101
left a comment
There was a problem hiding this comment.
Review — architecture-container template
C4 fidelity is strong and first-hand: container-as-application/data-store, the non-deployability
rule for components, the container diagram's deployment exclusion, and the four-level hierarchy are
all correct against the C4 pages. Crucially, this template does not redefine a C4 container as a
Docker/OS container — I checked that specifically, since it is the classic failure. Four findings.
High — the research note is credited with a mapping it does not contain
The TEAM_KNOWLEDGE entry at :87 states the note "groups the three architecture template issues
(#1326 component, #1327 container, #1328 context) under the C4 model's System Context, Container and
Component diagram layers."
I read launchpad/Research/project-documentation-templates.md at PR #1466's head myself: 456 lines,
and grep -coE '#[0-9]{3,4}' returns 0 — it contains no issue references at all, and is a
generic, issue-agnostic catalogue. The rest of the same entry is verbatim-correct (the note does say
"Diagrams, not prose — it slots into arc42 §3/§5/§7 rather than competing with it", and the
arc42-too-heavy passage checks out).
So the substance is sound and the fix is narrow: the issue-to-C4-layer mapping is this batch's own
contribution and must be attributed to the author. provided_by exists precisely to stop a source
being credited with something it does not say. Sibling #1528 carries the identical misattribution,
so the likely origin is the shared dispatch brief — worth correcting in both. Note your other
research-note entry at :89 is exemplary: an absence claim with its verification method stated, and
it checks out.
Medium — the worked example classifies a library crate as a C4 component
The buzz-db row concludes it is "a component within that container". The "not a container" half is
correct and well-cited; the "is a component" half contradicts the source. From
c4model.com/abstractions/component's FAQ, read in full:
"Is a Java JAR, C# assembly, DLL, module, package, namespace, folder etc a component?
Perhaps but, again, typically not. The C4 model is about showing the runtime units
(containers) and how functionality is partitioned across them (components), rather than
organisational units such as Java JAR files, C# assemblies, DLLs, modules, packages, namespaces or
folder structures."
A Rust library crate is the direct analogue, and the row's stated reasoning is exactly "it is a
library crate, therefore a component" — the inference C4 rejects. architecture-component.md:110-116
quotes the correct definition. This table is the template's only worked illustration of the
container/component line, so it teaches the wrong test at the one place an author will copy.
Medium — classes are C4's Code level, not the component level
:184-187 ("down into component-level internals (classes, modules, request handlers)") and :375
("it does not describe a container's internal modules, classes or request handlers") both place
classes at the component level. The C4 page says a component "is a way to step up one level of
abstraction from the code-level building blocks ... (i.e. classes and interfaces)", and
architecture-component.md:145-153 places classes at Code level accordingly. The two templates hand
an author two different accounts of what the sibling below owns — the exact failure the Boundary
sections exist to prevent.
Medium — the "Not Docker!" disambiguation is absent while a Dockerfile is endorsed as evidence
c4model.com/abstractions/container opens with the literal words "Not Docker!" and its FAQ notes
that "many software developers now associate the term 'container' with Docker" — the most-emphasised
point on the page you cite. This template never carries that disambiguation, and :306 lists "a
Dockerfile" among the citations that make a container's existence and technology a FACT, with no
caveat — in a repository that ships a crates/buzz-backend-kubernetes crate. Your operative test at
:277-280 ("would the system stop working if this stopped running?") is C4-correct, so this is not a
redefinition — but for a template whose job is teaching a term the source insists is misread,
omitting the disambiguation while endorsing Dockerfile-as-evidence is a concrete usability defect.
Not findings, ruled out on evidence
- Index registration: the corpus
AGENTS.mdandREADME.mdboth state that indexes are
generated derived views, never hand-authored, and the ten-step "Creating a node" procedure has
no registration step. All 26 template PRs leavingAGENTS.mduntouched is correct. - CI green at head (latest run per check); node validates clean.
Reviewed by tucktuck101's review lane. Every failing claim reported above was reproduced by me against this PR head before posting.
What
Adds
launchpad/docs/corpus/templates/architecture-container.md(
id: corpus-template-architecture-container) — the corpus template for acontainer-scoped architecture document, per PRD #605.
Closes #1327
Issue type
Task
Note on DoD
Issue #1327's Definition of Done carries a MUST/SHOULD/enforcement/exception
checklist copied verbatim from the standards-track issues (the ones that
produced
standards/confidence.mdandstandards/decision-references.md).That checklist describes a policy/standard node, not a template. This node is
built against #605's actual template acceptance criterion instead: every
template states its purpose, required sections, evidence expectations and the
industry model/standard it adapts. The rest of #1327's checklist (one
hand-authored document, schema-valid front matter, one independently
maintainable idea, traceable FACT/INFERENCE/TEAM_KNOWLEDGE claims, links
instead of duplication, checked against the recorded revision, clean validator
run) is generic to any corpus node and is honoured as written. The document's
own "Scope and authority" section states this same note in place.
typechoiceUsed
type: governance.node.schema.json's enum has notemplateorpolicyvalue (PRD #602's corpus-surface list only). Checkedschema/README.mdandschema/COMPATIBILITY.mddirectly (not just thebrief) — neither names a template- or policy-specific enum value;
COMPATIBILITY.md's only content is the v1 history entry and theadditive-change rule.
governancematches every existing corpusmeta-document except
AGENTS.md(type: agent):README.md,standards/confidence.md,standards/decision-references.md. Notedexplicitly in the node's own evidence ledger and body that a real instance
written from this template takes
type: architectureinstead — that valueis in the enum precisely because containers are a PRD #602 corpus surface;
this template document itself is not such an instance.
Relationships
Declared none, and checked before deciding that rather than assuming it.
git ls-tree -r --name-only origin/launchpad -- launchpad/docs/corpusatcommit
a44cf52fc740ebebbdd671427480d14f0bce0115shows exactly fourvalidated content nodes:
corpus-agents,corpus-readme,corpus-standard-confidence,corpus-standard-decision-references(
schema/excluded from validation). None has architecture, C4, arc42,containers or templates as its subject, so an edge to any of them would be a
citation duplicate of what the evidence ledger already cites directly, not a
substantive typed relationship. The document's own "Scope and omissions"
section names the most likely future edge (
implementstargeting theper-type diagram standard, #1312, once it merges) and explains why the two
sibling architecture templates (#1326, #1328) can't be targeted today — all
three are being authored in parallel with none merged when review starts on
the others, so any edge between them would validate in a worktree and fail
against
origin/launchpad.Research-note grounding
launchpad/Research/project-documentation-templates.md(unmerged PR #1466)groups the three architecture template issues under C4's System
Context/Container/Component layers and states C4 is "diagrams, not prose"
that "slots into arc42 §3/§5/§7." Cited as
TEAM_KNOWLEDGEattributed tolaunchpad-26/buzz#1466 (unmerged research note), neverFACT, per thebatch brief. Everything else the document asserts about C4 and arc42 was
independently fetched and read from the primary sources
(
c4model.com/abstractions/container,c4model.com/diagrams/container,c4model.com/diagrams/deployment,c4model.com,arc42.org/overview,docs.arc42.org/section-5/) and cited asFACTagainst those URLs, notagainst the note — including the container-vs-deployment boundary, which the
note doesn't actually discuss at all (it names only C4's four core diagrams).
That gap is called out explicitly in the ledger rather than silently
resolved either way.
One place where checking the primary source mattered: the note doesn't cover
runbooks-vs-postmortems overlap or the container/deployment boundary, so this
document's boundary claim against #1336 rests entirely on
c4model.com's ownpages, independently confirming the split the brief anticipated rather than
inheriting it from the note.
Verify-gate and validator evidence
Run as a lone command from this worktree immediately before commit; the
pre-commit hook's
.claude/.verifiedgate accepted the commit.All 17
UNVERIFIEDnotices are the expected shapes (a commit-referenceprovenance citation, and external URLs to c4model.com/arc42.org/GitHub that
the validator can't pin or open) — none are errors, and none rest on a
citation form that isn't legitimately unverifiable by this offline checker.
Process notes
(1) an evidence citation using
git ls-tree ... (run at revision ...)anda bare
launchpad-26/buzz#1336string, neither of which match any ofvalidate.py's recognised citation shapes and would have hard-failed —reformatted to a tool-result shape and a proper GitHub issue URL
respectively; (2) the "Relationships an instance node should consider"
section originally recommended the container document hand-author a
referencesedge down to its component children, which contradictspart-of's documented forward direction and generatedhas-partinverse— corrected to have the component document declare
part-ofupwardinstead, and separated the
depends-on-vs-decision-citation mechanismsthat had been conflated in the same section.
review provider (Codex) as currently unavailable; a same-model
(self-adversarial) review pass was substituted, per the batch brief.
Escalations
None filed. The one candidate the batch brief flagged — whether this
template's boundary against #1336's deployment template is genuinely
ambiguous — was checked directly against
c4model.com's Container andDeployment diagram pages rather than escalated: the primary source states
plainly that the Container diagram "says very little about deployment
aspects... because it will likely vary across different environments" and
that a Deployment diagram is a distinct diagram type. The boundary is not
ambiguous at the primary-source level, so no issue was filed.