Skip to content

[Feature] Architecture vision + DFD + sequence diagram templates #224

@atlas-apex

Description

@atlas-apex

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

  • 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.

Effort Estimate

TBD

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium — plan-worthy, not urgentenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions