Skip to content

docs(corpus): add architecture-container template - #1529

Merged
tucktuck101 merged 1 commit into
launchpadfrom
task/1327-corpus-template-architecture-container
Aug 28, 2026
Merged

docs(corpus): add architecture-container template#1529
tucktuck101 merged 1 commit into
launchpadfrom
task/1327-corpus-template-architecture-container

Conversation

@serina-mcfall

@serina-mcfall serina-mcfall commented Aug 27, 2026

Copy link
Copy Markdown

What

Adds launchpad/docs/corpus/templates/architecture-container.md
(id: corpus-template-architecture-container) — the corpus template for a
container-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.md and standards/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.

type choice

Used type: governance. node.schema.json's enum has no template or
policy value (PRD #602's corpus-surface list only). Checked
schema/README.md and schema/COMPATIBILITY.md directly (not just the
brief) — neither names a template- or policy-specific enum value;
COMPATIBILITY.md's only content is the v1 history entry and the
additive-change rule. governance matches every existing corpus
meta-document except AGENTS.md (type: agent): README.md,
standards/confidence.md, standards/decision-references.md. Noted
explicitly in the node's own evidence ledger and body that a real instance
written from this template takes type: architecture instead — that value
is 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/corpus at
commit a44cf52fc740ebebbdd671427480d14f0bce0115 shows exactly four
validated 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 (implements targeting the
per-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_KNOWLEDGE attributed to
launchpad-26/buzz#1466 (unmerged research note), never FACT, per the
batch 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 as FACT against those URLs, not
against 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 own
pages, independently confirming the split the brief anticipated rather than
inheriting it from the note.

Verify-gate and validator evidence

$ python3 -m unittest discover -s launchpad/docs/corpus/schema/tests -p "test_*.py" -v
...
Ran 27 tests in 0.037s
OK

Run as a lone command from this worktree immediately before commit; the
pre-commit hook's .claude/.verified gate accepted the commit.

$ python3 launchpad/project-intelligence/corpus/validate.py
...
PASS  corpus validation found no errors; 17 item(s) reported unverified

All 17 UNVERIFIED notices are the expected shapes (a commit-reference
provenance 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

  • Self-review caught and fixed two real defects before this PR was opened:
    (1) an evidence citation using git ls-tree ... (run at revision ...) and
    a bare launchpad-26/buzz#1336 string, neither of which match any of
    validate.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
    references edge down to its component children, which contradicts
    part-of's documented forward direction and generated has-part inverse
    — corrected to have the component document declare part-of upward
    instead, and separated the depends-on-vs-decision-citation mechanisms
    that had been conflated in the same section.
  • Cross-model review was not run. Issue task: the mandatory cross-model review gate has a single provider, and it is unavailable #1467 records the cross-model
    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 and
Deployment 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.

Defines the required sections, evidence expectations and industry
grounding (C4 model Container diagram + arc42 section 5) for a
container-scoped architecture corpus node, per PRD #605's real
template acceptance criterion.

Closes #1327

Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>

@tucktuck101 tucktuck101 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.md and README.md both 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 leaving AGENTS.md untouched 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

task: define the architecture container corpus template

2 participants