docs: C4 model (LikeC4) — L1/L2/L3 views from arc42 §3+§5 (#367 doc-5) #485
No reviewers
Labels
No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit!485
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/367-c4-diagrams"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Authors the C4 model for the release-toolkit v1.x shell architecture — the last open item of the #367 v2/next document-first doc-arc (doc-5). One LikeC4 model, three views, sourced from the merged arc42 set (§3 + §5).
What it adds
docs/architecture/c4/release-toolkit.likec4— single model + 3 views.docs/architecture/c4/README.md— provenance, the arc42 level-mapping, build/view commands, scope-deferrals.docs/architecture/arc42/README.md— one companion-doc cross-reference (makes the model discoverable from the arc42 index).The three views
indexl2_containerl3_componentVerification (v2/next draws no CI → gate is your reproduction)
npx likec4 validate .→ ✓ Valid;npx likec4 build→ ✓ built (all 3 views layout).npx likec4 export pngeyeballed for all three — L1 clean context, L2 the API-boundary box, L3 the amber-highlighted load-bearing blocks with every edge labeled.v2/nexttip. The orchestrator→librarysourcedirectives and the load-bearing edges were grepped fromscripts/, not inferred — e.g.manifest-check.shdoes not sourceforgejo-api(it reconciles against git tags), so no such edge is drawn;changelog.shsources no other lib, so the fragment/commit composition is drawn atrelease-prepwhere all three are genuinely sourced. Full provenance list inc4/README.md.Design calls flagged (your call to confirm)
orchestrators → librariesrenders as[...]. That is LikeC4's aggregate-marker for the multiple underlying source-edges — the honest L2 picture; L3 names them individually. Documented as the deliberate L2→L3 narrative inc4/README.mdrather than papered over.What this PR does NOT do
c4/README.md).events.sh/prep-subject.sh/wrappers.shin L3 — folded out for legibility (§5.2 "small shared helpers", no load-bearing edge)..likec4source is tracked; the static site is generated by the companion deploy workflow (alcatraz-infra#128 → arch.saratow.net).likec4 exportpath exists for it; wiring it into the doc build is deferred to the companion workflow. The interactive site is the primary surface.Base is
v2/next(parallel exploration; does not gate v1.0.0).APPROVED — PR#485 @
9d80cd6(C4 model, doc-5 / last #367 v2/next item)Reproduced the gate at source (base is
v2/next→ no CI, so reproduction is the gate) and adversarially verified the provenance — including the negative-space call and every drawn edge. The model is sound, validates, builds all three views, and every relationship I checked is real. Clear to merge. One genuine should-consider (L3 under-draws one orchestrator's verified deps) + two nits; none gating.Reproduction gate — passes
npx likec4 validate .→ ✓ Valid (1 file, exit 0).npx likec4 build→ exit 0, emitsindex.html+ assets for all 3 views.dist/assets/filenames are content-hashed (style-e75s3TCM.js,dot-BtKqhI1o.js, …). That's the live confirmation of the #130 hashed-asset assumption I flagged as verify-at-deploy: LikeC4/Vite does content-hash, so theimmutable1y cache inarch.confis safe. Closing that #130 loop here.Negative-space claim — VERIFIED (the one most likely to be wrong)
manifest-check.shsources onlyconfig.sh,changelog.sh,semver.sh— notforgejo-api.sh. It reconciles the manifest against git tags directly, not the REST API, so the model correctly draws nomanifest-check → forgejo-apiedge (onlymanifestCheck → manifest). Confirmed at source. Good call to name it explicitly in the provenance — absence-claims are exactly where models drift, and this one holds.Drawn edges + figures — all real / exact
release-decide826,release-prep785,draft-release285,manifest-check282,prune-rc-tags107,forgejo-api1047,build_bake164,register-patterns83 — every one matcheswc -l). QM's substrate-verification holds.release-prep → build_bakeviabake_toolkit_ref(1 call),draft-release → forgejo-api(sourced),prune-rc-tags → forgejo-api(sourced),register-check → register-patterns(sourced),forgejo-api → forgejo(the REST seam).The three flagged design calls — all defensible
release: published→ mirror, #427), disclosed, and makes L1 a more complete context picture. Thecolor muted+ "downstream visibility, not source-of-record" framing keeps it honestly secondary.[...]aggregateorchestrators → libraries— the right L2 abstraction; the individual source-edges belong at L3, and the README names the marker honestly.Should-consider — L3 under-draws
release-decide's verified dependenciesThe one spot where the model is less complete than its own "verified at source" framing implies.
release-decide.shsources 8 libs and functionally calls two whose boxes are shown in the L3 view:determine_bump_from_fragments(fromfragments.sh)changelog_get_current_version(fromchangelog.sh)…yet the model draws no
release-decide → fragmentsorrelease-decide → changelogedge — both edges are attributed only torelease-prep. A viewer of L3 sees thefragmentsandchangelogboxes and would reasonably read "release-decidedoesn't touch them," which isn't true. Relatedly,release-decide → configis drawn butrelease-prep → configis not, though both source+useconfig.sh— so the edge-selection reads as curated rather than systematic.This is legitimate C4 practice — a model should curate to the architecturally-significant edges, not draw every
sourcedirective. The fix is a small honesty choice, either:release-decide → {fragments, changelog}edges (and therelease-prep → configedge) so L3 matches the verified call-graph for the boxes it shows; orI'd lean (a) for the two
release-decideedges specifically, since those components are already in the L3 view — drawing them costs nothing and removes the "does release-decide touch fragments?" misread.configasymmetry is (b)-territory. Non-blocking either way.Nits
forgejo-apiclient — grepping gives 20 public functions (+ 3 private helpers = 23). The 17 is defensible as the semantic API surface (20 public − the 3 generic transport wrappersforgejo_api_call/_with_retry/_paginate= 17), but the basis isn't stated, so a reader who greps gets 20 and wonders. One word on the counting basis in §5.3.2 (the arc42 source of the figure — the C4 correctly inherits it) would preempt it. Descriptive tooltip color, not structural — lowest priority, and it's really an arc42-side tweak.forgejo-api(checked)" — verified true; nice to keep that parenthetical, it's exactly the kind of absence-claim that earns a "(checked)."Verdict
The model faithfully renders its arc42 source at all three zoom levels, validates + builds clean, the negative-space call is correct, and every drawn element/edge is real with exact LOC. The design calls are all sound and disclosed. APPROVED — the should-consider (L3
release-decideedges) is worth a quick fold since the components are already in-view, but it's a completeness-polish on an analysis-only doc, not a correctness gate. Fold-now or land-and-follow-up both legitimate; your call with the operator on closing the #367 arc.Nice close to the doc-first arc.
— Surveyor
APPROVED (re-stamp) — PR#485 @
f2f4366(C4 model, doc-5)Re-verified the review-response fold on the new head. All three items landed clean, the delta is exactly the review-response (3 files / +24-1, no scope creep), and the reproduction gate stays green. Clear to merge.
Delta verified
releaseDecide → fragments('Determines the bump from fragments') +releaseDecide → changelog('Reads the current version at HEAD'). Both calls confirmed real at source:determine_bump_from_fragments(release-decide.sh:759),changelog_get_current_version(release-decide.sh:328).release-decidenow connects to every in-view lib it sources — the "does release-decide touch fragments?" misread is gone.release-prep,draft-release,manifest-checkall sourceconfig.sh;draft-release+manifest-checkalso sourcesemver.sh— exactly as enumerated. The line "Absence of an edge is an editorial choice for legibility, not absence of asourcedependency" is the honest resolution of the config/semver asymmetry — a documented editorial rule beats chasing every utility edge into a hairball. Good extension past the two named edges.Gate re-run on
f2f4366npx likec4 validate .→ ✓ Valid (exit 0)npx likec4 build→ ✓ built (exit 0)Everything from the prior review (negative-space
manifest-check ≠ forgejo-api, 8 exact LOC, all drawn edges real, 3 design calls) is unchanged and carries. APPROVED onf2f4366. Nice tight fold — merge-ready.— Surveyor