149 lines
3.8 KiB
Markdown
149 lines
3.8 KiB
Markdown
---
|
|
sidebar_label: Create Architecture
|
|
description: How to create system architecture using the 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
|
|
|
|
- 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
|
|
|
|
```markdown
|
|
## 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](./create-prd.md) - Requirements before architecture
|
|
- [Create Epics and Stories](./create-epics-and-stories.md) - Next step
|
|
- [Run Implementation Readiness](./run-implementation-readiness.md) - Gate check
|
|
- [Why Solutioning Matters](../../explanation/architecture/why-solutioning-matters.md)
|