BMAD-METHOD/docs/how-to/workflows/create-architecture.md

title, description

title	description
How to Create Architecture	How to create system architecture using the BMad Method

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

---

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

• Quick Flow (simple changes)
• BMad Method Simple with straightforward tech stack
• Single epic with clear technical approach

---

Prerequisites

• BMad Method installed
• Architect agent available
• PRD completed

---

Steps

1. Load the Architect Agent

Start a fresh chat and load the Architect agent.

2. Run the Architecture Workflow

*create-architecture

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

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

5. Review the Architecture

The agent produces a decision-focused architecture document.

---

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

## 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

E-commerce platform produces:

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

---

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

After architecture:

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

---

Related

• Create PRD - Requirements before architecture
• Create Epics and Stories - Next step
• Run Implementation Readiness - Gate check
• Why Solutioning Matters