Skip to main content

Stage 4 — Design Documents

Agents: bmad-agent-architect, bmad-create-architecture · Approvers: L1 Architect · L2 Tech Lead

Three independent design documents with embedded PlantUML diagrams — dual approval required.

warning

Stages 4 & 5 require L1 + L2 dual approval. The next stage is locked until both approve. The same person cannot provide both signatures.

  1. Invoke Architect Agent: System calls Skill: bmad-agent-architect → Skill: bmad-create-architecture
  2. Generate HLD — High-Level Design document
  3. Generate LLD — Low-Level Design document
  4. Generate Arch — Enterprise Architecture document
  5. PlantUML Diagrams rendered — java -jar tools\plantuml.jar -tpng — embedded in each .docx via add_picture()
  6. Design Enforcer Audit: agent-s4-design-enforcer reviews all three docs for completeness
  7. Architect L1 Approval — name + timestamp saved
  8. Tech Lead L2 Approval — name + timestamp saved; Stage 5 unlocks

Document contents​

DocumentSectionsDiagrams (PlantUML)
HLD§1 Overview, §2 Flow (Fig 1), §3 Components (Fig 2), §4 Tech Stack, §5 Security, §6 ScalabilityFig 1: Overall Flow (sequence) · Fig 2: Component Architecture (component)
LLD§1 DB Schema, §2 API Contracts, §3 Feature Sequences (one per PRD feature), §4 Error HandlingERD (class w/ <<entity>>) · One sequence diagram per feature (Figs 3–9)
Arch§1 Enterprise Context, §2 Deployment Zones (Fig 10), §3 Integration Points, §4 GovernanceFig 10: Enterprise Architecture (deployment or component with zones)

PlantUML pipeline rules​

  • .puml sources saved under docs/sdlc/diagrams/ — text-diffable in git
  • Rendered to PNG via java -jar plantuml.jar -tpng {file}.puml
  • PNG embedded in the correct section of each .docx via add_picture()
  • SMETANA layout engine used (no Graphviz dependency needed)
warning

Close Word files before generating — python-docx will fail if the file is open.

danger

Never use matplotlib, draw.io, or Mermaid — only PlantUML.

Artifacts (6 files): {ProjectName}_HLD.md · .docx, {ProjectName}_LLD.md · .docx, {ProjectName}_Arch.md · .docx, docs/sdlc/diagrams/*.puml + *.png