Skip to content
🤖 Consolidated, AI-optimized BMAD docs: llms-full.txt. Fetch this plain text file for complete context.
BMAD Logo BMAD Method

How to Create Architecture

Use the architecture workflow to make technical decisions explicit and prevent agent conflicts during implementation.

When to Use This

Section titled “When to Use This”
  • Multi-epic projects (BMad Method, Enterprise)
  • Cross-cutting technical concerns
  • Multiple agents implementing different parts
  • Integration complexity exists
  • Technology choices need alignment

When to Skip This

Section titled “When to Skip This”
  • Quick Flow (simple changes)
  • BMad Method Simple with straightforward tech stack
  • Single epic with clear technical approach

Prerequisites

Section titled “Prerequisites”
  • BMad Method installed
  • Architect agent available
  • PRD completed

Steps

Section titled “Steps”

1. Load the Architect Agent

Section titled “1. Load the Architect Agent”

Start a fresh chat and load the Architect agent.

2. Run the Architecture Workflow

Section titled “2. Run the Architecture Workflow”
*create-architecture

3. Engage in Discovery

Section titled “3. Engage in Discovery”

This is NOT a template filler. The architecture workflow:

  1. Discovers technical needs through conversation
  2. Proposes architectural options with trade-offs
  3. Documents decisions that prevent agent conflicts
  4. Focuses on decision points, not exhaustive documentation

4. Document Key Decisions

Section titled “4. Document Key Decisions”

Work with the agent to create Architecture Decision Records (ADRs) for significant choices.

5. Review the Architecture

Section titled “5. Review the Architecture”

The agent produces a decision-focused architecture document.

What You Get

Section titled “What You Get”

An architecture.md document containing:

  1. Architecture Overview - System context, principles, style
  2. System Architecture - High-level diagram, component interactions
  3. Data Architecture - Database design, state management, caching
  4. API Architecture - API style (REST/GraphQL/gRPC), auth, versioning
  5. Frontend Architecture - Framework, state management, components
  6. Integration Architecture - Third-party integrations, messaging
  7. Security Architecture - Auth/authorization, data protection
  8. Deployment Architecture - CI/CD, environments, monitoring
  9. ADRs - Key decisions with context, options, rationale
  10. FR/NFR-Specific Guidance - Technical approach per requirement
  11. Standards and Conventions - Directory structure, naming, testing

ADR Format

Section titled “ADR Format”
## ADR-001: Use GraphQL for All APIs


**Status:** Accepted | **Date:** 2025-11-02


**Context:** PRD requires flexible querying across multiple epics


**Decision:** Use GraphQL for all client-server communication


**Options Considered:**
1. REST - Familiar but requires multiple endpoints
2. GraphQL - Flexible querying, learning curve
3. gRPC - High performance, poor browser support


**Rationale:**
- PRD requires flexible data fetching (Epic 1, 3)
- Mobile app needs bandwidth optimization (Epic 2)
- Team has GraphQL experience


**Consequences:**
- Positive: Flexible querying, reduced versioning
- Negative: Caching complexity, N+1 query risk
- Mitigation: Use DataLoader for batching

Example

Section titled “Example”

E-commerce platform produces:

  • Monolith + PostgreSQL + Redis + Next.js + GraphQL
  • ADRs explaining each choice
  • FR/NFR-specific implementation guidance

Tips

Section titled “Tips”
  • Focus on decisions that prevent agent conflicts
  • Use ADRs for every significant technology choice
  • Keep it practical - don’t over-architect
  • Architecture is living - update as you learn

Next Steps

Section titled “Next Steps”

After architecture:

  1. Create Epics and Stories - Work breakdown informed by architecture
  2. Implementation Readiness - Gate check before Phase 4
Section titled “Related”