You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As a Tech Lead drafting an architecture for a new feature or system, I want a vision template, a DFD template, and a sequence-diagram template so I can reach for a structured starting point rather than a blank page or an ad-hoc Mermaid block buried inside a one-off design doc.
Acceptance Criteria
New template at templates/architecture/vision.md — north-star architecture document covering: scope statement, principles, target-state Mermaid C4 L1, current-state vs target-state delta, multi-quarter migration path, "things we explicitly chose NOT to build", review cadence
New template at templates/architecture/dfd.md — Data Flow Diagram template with Mermaid flowchart skeleton, trust-boundary subgraph convention (dashed), data-label-on-arrow convention, brief usage notes ("DFDs are the natural input to a STRIDE threat model — see templates/audits/threat-model.md")
New template at templates/architecture/sequence.md — Mermaid sequenceDiagram template for request-flow walkthroughs (auth handshake, payment flow, etc.), with notes on when to use vs C4 L3 component diagrams
Each template has a header explaining when to use it (vs the existing C4 L1/L2 templates) and what the artefact is for
templates/architecture/ README (or one-line table in CLAUDE.md § Templates) updated to surface the new templates alongside the existing C4 L1 + L2 entries
Cross-references: templates/audits/threat-model.md references templates/architecture/dfd.md after the DFD-section work in the sibling [Chore: Add DFD to threat-model template] ticket; templates/technical-design.md § Architecture references all three new templates as alternatives to the inline ASCII placeholder
Design Notes
No UI changes. Pure markdown additions.
The vision template's biggest job is the current-state vs target-state delta — that's the section that turns "wishful architecture diagram" into "actionable migration roadmap". Without that section the template degenerates into a pretty picture nobody acts on.
DFD and sequence templates are short — Mermaid skeletons with conventions baked in. The framework already has a strong precedent (AgDR-0003 chose Mermaid as the diagram tool, used in C4 templates).
Out of Scope
C4 L3 (Component) and L4 (Code) templates — the L3 is sometimes useful for designing inside a single container; L4 is rarely worth the maintenance. File separately if needed.
Architecture review process / cadence (who reviews, when, how) — that's a workflow question, not a template question. File a separate [Docs] ticket if needed.
Auto-generation of any diagram from code — out of scope; the templates are operator-authored.
User Story
As a Tech Lead drafting an architecture for a new feature or system, I want a vision template, a DFD template, and a sequence-diagram template so I can reach for a structured starting point rather than a blank page or an ad-hoc Mermaid block buried inside a one-off design doc.
Acceptance Criteria
templates/architecture/vision.md— north-star architecture document covering: scope statement, principles, target-state Mermaid C4 L1, current-state vs target-state delta, multi-quarter migration path, "things we explicitly chose NOT to build", review cadencetemplates/architecture/dfd.md— Data Flow Diagram template with Mermaidflowchartskeleton, trust-boundary subgraph convention (dashed), data-label-on-arrow convention, brief usage notes ("DFDs are the natural input to a STRIDE threat model — seetemplates/audits/threat-model.md")templates/architecture/sequence.md— MermaidsequenceDiagramtemplate for request-flow walkthroughs (auth handshake, payment flow, etc.), with notes on when to use vs C4 L3 component diagramstemplates/architecture/README (or one-line table inCLAUDE.md§ Templates) updated to surface the new templates alongside the existing C4 L1 + L2 entriestemplates/audits/threat-model.mdreferencestemplates/architecture/dfd.mdafter the DFD-section work in the sibling [Chore: Add DFD to threat-model template] ticket;templates/technical-design.md§ Architecture references all three new templates as alternatives to the inline ASCII placeholderDesign Notes
No UI changes. Pure markdown additions.
The vision template's biggest job is the current-state vs target-state delta — that's the section that turns "wishful architecture diagram" into "actionable migration roadmap". Without that section the template degenerates into a pretty picture nobody acts on.
DFD and sequence templates are short — Mermaid skeletons with conventions baked in. The framework already has a strong precedent (AgDR-0003 chose Mermaid as the diagram tool, used in C4 templates).
Out of Scope
[Docs]ticket if needed.Effort Estimate
TBD