feat(#50): Mermaid C4 architecture diagrams — L1 + L2 templates + dogfood by atlas-apex · Pull Request #69 · me2resh/apexyard

atlas-apex · 2026-04-17T09:13:44Z

Summary

Ships v1 of architecture-diagram support per issue #50. Mermaid C4 only — GitHub renders it inline, no Java/Docker/Go install required. L3+ precision and Structurizr DSL deferred to dedicated follow-ups (#67, #68) that land only when a project actually needs them.

What changed

docs/agdr/AgDR-0003-mermaid-c4-for-diagrams.md — decision record. Options matrix, weighted dimensions (GitHub-inline render + zero dep + single-source all favour Mermaid), consequences, deferred follow-ups.
templates/architecture/c4-context.md — L1 template with a filled-in Mermaid C4Context block and inline guidance on what goes/doesn't go in L1.
templates/architecture/c4-container.md — L2 template with a Mermaid C4Container block and L1↔L2 consistency guidance.
docs/architecture/apexstack-context.md — dogfood L1 for ApexStack itself (ops role, framework fork, Claude Code + GitHub + managed projects + upstream).
docs/architecture/apexstack-container.md — dogfood L2. Documents the non-traditional interpretation of "container" for ApexStack (folder-scoped file sets interpreted by Claude Code / the user / GitHub) and explains why.
docs/multi-project.md — new "Architecture diagrams" subsection with the directory split (framework-wide / per-project-apexstack-docs / per-project-repo).
CLAUDE.md — templates table gains two rows.

Testing

Doc + template-only change. No executable code; no unit tests.

Manual verification:

Both dogfood diagrams render on the GitHub branch preview (verify before merge — GitHub renders Mermaid in the file view)
Templates parse as valid Mermaid (copy-paste into Mermaid Live Editor, diagram renders)
AgDR links in docs/multi-project.md and CLAUDE.md resolve

Follow-up tickets filed with this PR

[Feature] /handover skill generates a stub C4 L2 container diagram #67 — /handover skill auto-generates a stub L2 container diagram from repo signals (package.json, Dockerfile, docker-compose.yml, etc.). Meaningful skill change — bundled separately.
[Feature] Structurizr DSL as escape hatch for L3+ C4 diagrams #68 — Structurizr DSL as escape hatch for L3+ precision. Explicit "NOT NOW" — open only when a project hits Mermaid's C4 ceiling.

Glossary

Term	Definition
C4 model	A 4-level architecture-diagram convention (Context / Container / Component / Code) from Simon Brown. Level = zoom dimension, not quality tier.
L1 context	The system as a single box + every person and external system it touches
L2 container	The system broken down into deployable / runnable units (web app, API, DB, worker)
Mermaid C4	GitHub-native Markdown-embedded C4 diagramming dialect. Renders inline in file previews. Beta support in Mermaid, sufficient for L1/L2
AgDR	Agent Decision Record — lightweight `docs/agdr/AgDR-NNNN-slug.md` file capturing why a technical decision was made (options, tradeoffs, consequences)
dogfood	A vendor using their own product in production. Here: ApexStack documents its own architecture using the diagram convention it ships.

Closes feat: architecture diagram support in documentation — C4 model #50
Deferred follow-ups: [Feature] /handover skill generates a stub C4 L2 container diagram #67, [Feature] Structurizr DSL as escape hatch for L3+ C4 diagrams #68
Decision rationale: docs/agdr/AgDR-0003-mermaid-c4-for-diagrams.md

…food Ships v1 of architecture-diagram support per issue #50. Chooses Mermaid C4 over Structurizr DSL / PlantUML / D2 — documented in docs/agdr/AgDR-0003. Rationale: Mermaid renders inline on GitHub with zero tooling. Every user sees diagrams without Java/Docker/Go installs, and the Markdown file IS the source (no DSL + rendered-PNG two-commit dance). C4 fidelity is "good enough" for L1/L2, which is the target scope. L3+ precision is deferred. What ships: - AgDR-0003 documenting the tool choice with the full options matrix and weighted dimensions - templates/architecture/c4-context.md — L1 context template - templates/architecture/c4-container.md — L2 container template - docs/architecture/apexstack-context.md — dogfood: ApexStack's own L1 (person, system boundary, external systems — GitHub, Claude Code, managed projects, upstream) - docs/architecture/apexstack-container.md — dogfood: ApexStack's own L2 (the "containers" are folder-scoped file sets interpreted by Claude Code + GitHub + the user — non-traditional but useful) - docs/multi-project.md — new "Architecture diagrams" subsection explaining the convention, template locations, and the framework-wide / per-project / per-repo directory split - CLAUDE.md — templates table gains two rows (c4-context, c4-container) Deferred to follow-up tickets (filed with this PR): - #67 /handover skill auto-generates stub L2 from repo signals - #68 Structurizr DSL escape hatch for L3+ precision Closes #50

atlas-apex

Code Review: PR #69

Commit: 51598c93e13045288613cc82cc824d62a7b1be43

Summary

Docs-only PR shipping Mermaid C4 as the architecture-diagram convention for ApexStack: an AgDR capturing the tool choice, L1 + L2 templates, and ApexStack's own dogfood diagrams.

Checklist Results

Architecture & Design: Pass (N/A — docs only; AgDR-0003 covers the decision)
Code Quality: Pass (N/A — docs only)
Testing: Pass (N/A — docs only; manual Mermaid render verification documented)
Security: Pass (N/A — no code, no secrets)
Performance: Pass (N/A)
PR Description & Glossary: Pass (6 terms: C4 model, L1 context, L2 container, Mermaid C4, AgDR, dogfood)
Technical Decisions (AgDR): Pass (AgDR-0003 linked in PR body, in docs/multi-project.md, and covers all 4 alternatives from #50)

Findings

Mermaid syntax — valid. Close read of all four mermaid blocks:

C4Context: Person(), System(), System_Ext(), Rel() keywords correct, all strings quoted, commas balanced.
C4Container: System_Boundary(id, "label") { ... } braces match in both dogfood and template. Container(), ContainerDb(), Rel() all well-formed.
No missing commas in Person/Rel nodes; no trailing commas; no stray keywords.

Dogfood accuracy — verified. Against workspace/apexstack/:

31 skills claimed in diagram → ls .claude/skills | wc -l = 31 ✓
19 roles claimed → find roles -name '*.md' = 19 ✓
Top-level dirs referenced (roles/, workflows/, templates/, golden-paths/, projects/, .claude/rules/, .claude/hooks/, .claude/skills/, .claude/agents/, CLAUDE.md, onboarding.yaml, apexstack.projects.yaml) all present.
Note: CLAUDE.md's own "Available skills" header still says 27 (pre-existing drift, not this PR's scope).

AgDR quality — strong. Options matrix covers all four alternatives from #50 (Mermaid / Structurizr / PlantUML / D2). Weighted dimensions are explicit and the tie-breakers (GitHub inline render + single-source) are well-argued. Deferred follow-ups link to #67 and #68 with explicit "NOT NOW" rationale.

Template usability — good. {Project Name} placeholder is consistent; per-line "remove if N/A" guidance present; L1↔L2 consistency note present; commit-and-render workflow stated.

Link hygiene — consistent. PR body → AgDR-0003, docs/multi-project.md → AgDR-0003, CLAUDE.md templates table gains the two rows. All resolve.

Suggestions (non-blocking)

None worth holding the PR for. Optionally, a future pass could align CLAUDE.md's "Available skills (27)" header with the 31-skill reality the container diagram documents.

Verdict

APPROVED — docs-only change, Mermaid validates by inspection, dogfood matches the fork, AgDR reasoning is solid.

Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 51598c93e13045288613cc82cc824d62a7b1be43

- MD032: add blank lines before two bulleted "Candidates"/"Updates when" lists in docs/architecture/apexstack-context.md and apexstack-container.md - lychee: c4model.com#SystemContextDiagram / #ContainerDiagram anchors don't exist on the current c4model.com. Repoint to the per-level subpages (`/diagrams/system-context`, `/diagrams/container`) which return HTTP 200 — verified locally.

atlas-apex

Re-review at 99d6f83 — carrying previous approval forward.

Incremental diff vs 51598c9 is purely mechanical:

Two blank lines added before bulleted lists in docs/architecture/apexstack-{context,container}.md (markdownlint MD032)
Two c4model.com fragment URLs repointed to /diagrams/system-context and /diagrams/container (lychee fix)

No content or semantic changes. CI green. Approval stands.

Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 99d6f8390408322ac9e23ae6ae517beacd63245d

rafik-wahid-cubeish

Code Review — Rex

Commit reviewed: 99d6f8390408322ac9e23ae6ae517beacd63245d

Summary

Doc + template-only PR. The structure, AgDR quality, and Mermaid C4 approach are all solid. Two blocking issues around product naming must be fixed before merge; one nit about a volatile skill count.

BLOCKING — Product name is wrong throughout dogfood files

The canonical framework name is ApexYard (confirmed in CLAUDE.md, onboarding.yaml, README, and the GitHub repo me2resh/apexyard). This PR consistently uses "ApexStack" in every dogfood artifact.

Files affected:

File	Problem
`docs/architecture/apexstack-context.md`	Filename and all diagram/prose content uses "ApexStack"
`docs/architecture/apexstack-container.md`	Filename and all diagram/prose content uses "ApexStack"
`docs/multi-project.md`	"ApexStack dogfoods its own convention"
`docs/agdr/AgDR-0003-mermaid-c4-for-diagrams.md`	Title sentence: "as the diagramming format for ApexStack-managed projects"

Required changes:

Rename apexstack-context.md → apexyard-context.md
Rename apexstack-container.md → apexyard-container.md
Replace "ApexStack" → "ApexYard" everywhere in those files and in docs/multi-project.md
Update the AgDR title + body to reference "ApexYard" instead of "ApexStack"
Update cross-references from c4-container.md and c4-context.md that point at the dogfood examples (apexstack-container.md / apexstack-context.md)

BLOCKING — AgDR frontmatter has wrong repo slug

ticket: me2resh/apexstack#50

Should be:

ticket: me2resh/apexyard#50

Nit — Hardcoded skill count will go stale

In docs/architecture/apexstack-container.md (to be renamed), the skills container label reads:

"Slash commands — /setup, /handover, ... etc. (31 skills)"

The repo already has 54 skills. Drop the inline count; the surrounding prose already says "see CLAUDE.md § 'Available skills'" — that's the right single source of truth.

Checklist

Area	Status
Architecture	✅ No code — doc + template only
Code quality	✅ Well-structured, consistent guidance prose
Testing	✅ Doc-only change; manual verification steps listed
Security	✅ No concerns
PR description — summary bullets	✅ Narrative, not label-only
PR description — Glossary	✅ Present, thorough
AgDR for technical decision	✅ AgDR-0003 records the Mermaid C4 vs Structurizr/PlantUML/D2 decision
Ticket link	✅ Closes #50
Naming — product name	❌ "ApexStack" throughout; must be "ApexYard"
AgDR ticket reference	❌ `me2resh/apexstack#50` → `me2resh/apexyard#50`

Verdict: CHANGES REQUESTED — fix the two blocking naming issues and the nit, then re-request review.

…s + dogfood (me2resh#69) * feat(me2resh#50): Mermaid C4 architecture diagrams — L1 + L2 templates + dogfood Ships v1 of architecture-diagram support per issue me2resh#50. Chooses Mermaid C4 over Structurizr DSL / PlantUML / D2 — documented in docs/agdr/AgDR-0003. Rationale: Mermaid renders inline on GitHub with zero tooling. Every user sees diagrams without Java/Docker/Go installs, and the Markdown file IS the source (no DSL + rendered-PNG two-commit dance). C4 fidelity is "good enough" for L1/L2, which is the target scope. L3+ precision is deferred. What ships: - AgDR-0003 documenting the tool choice with the full options matrix and weighted dimensions - templates/architecture/c4-context.md — L1 context template - templates/architecture/c4-container.md — L2 container template - docs/architecture/apexstack-context.md — dogfood: ApexStack's own L1 (person, system boundary, external systems — GitHub, Claude Code, managed projects, upstream) - docs/architecture/apexstack-container.md — dogfood: ApexStack's own L2 (the "containers" are folder-scoped file sets interpreted by Claude Code + GitHub + the user — non-traditional but useful) - docs/multi-project.md — new "Architecture diagrams" subsection explaining the convention, template locations, and the framework-wide / per-project / per-repo directory split - CLAUDE.md — templates table gains two rows (c4-context, c4-container) Deferred to follow-up tickets (filed with this PR): - me2resh#67 /handover skill auto-generates stub L2 from repo signals - me2resh#68 Structurizr DSL escape hatch for L3+ precision Closes me2resh#50 * fix: markdownlint blanks-around-lists + lychee c4model.com fragments - MD032: add blank lines before two bulleted "Candidates"/"Updates when" lists in docs/architecture/apexstack-context.md and apexstack-container.md - lychee: c4model.com#SystemContextDiagram / #ContainerDiagram anchors don't exist on the current c4model.com. Repoint to the per-level subpages (`/diagrams/system-context`, `/diagrams/container`) which return HTTP 200 — verified locally. --------- Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>

github-actions Bot added github-issue has-ticket labels Apr 17, 2026

atlas-apex commented Apr 17, 2026

View reviewed changes

me2resh approved these changes Apr 17, 2026

View reviewed changes

atlas-apex commented Apr 17, 2026

View reviewed changes

atlas-apex merged commit 7c6dcd3 into main Apr 17, 2026
3 checks passed

atlas-apex deleted the feature/#50-c4-mermaid-diagrams branch April 17, 2026 09:27

rafik-wahid-cubeish suggested changes May 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(#50): Mermaid C4 architecture diagrams — L1 + L2 templates + dogfood#69

feat(#50): Mermaid C4 architecture diagrams — L1 + L2 templates + dogfood#69
atlas-apex merged 2 commits into
mainfrom
feature/#50-c4-mermaid-diagrams

atlas-apex commented Apr 17, 2026

Uh oh!

atlas-apex left a comment

Uh oh!

atlas-apex left a comment

Uh oh!

Uh oh!

rafik-wahid-cubeish left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

atlas-apex commented Apr 17, 2026

Summary

What changed

Testing

Follow-up tickets filed with this PR

Glossary

Related

Uh oh!

atlas-apex left a comment

Choose a reason for hiding this comment

Code Review: PR #69

Summary

Checklist Results

Findings

Suggestions (non-blocking)

Verdict

Uh oh!

atlas-apex left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rafik-wahid-cubeish left a comment

Choose a reason for hiding this comment

Code Review — Rex

Summary

BLOCKING — Product name is wrong throughout dogfood files

BLOCKING — AgDR frontmatter has wrong repo slug

Nit — Hardcoded skill count will go stale

Checklist

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants