BMAD-METHOD/bmad-core/templates/memory-bank/systemPatterns-tmpl.md

System Patterns

Technical architecture, design patterns, and critical implementation decisions

System Architecture Overview

High-Level Architecture

[ASCII or text diagram showing major components and relationships]

Architectural Style

• Pattern: [e.g., Microservices, Monolith, Serverless]
• Rationale: [Why this architecture was chosen]
• Trade-offs: [What we gain vs. what we sacrifice]

Core Components

Component 1: [Name]

• Purpose: [What it does]
• Responsibilities: [Key functions]
• Technology: [Implementation details]
• Interfaces: [How others interact with it]
• Location: [Where to find the code]

Component 2: [Name]

• Purpose: [What it does]
• Responsibilities: [Key functions]
• Technology: [Implementation details]
• Interfaces: [How others interact with it]
• Location: [Where to find the code]

Design Patterns

Pattern 1: [Pattern Name]

• Where Used: [Components/modules using this pattern]
• Implementation: [How it's implemented]
• Benefits: [Why we use it]
• Example: [Code location or snippet]

Pattern 2: [Pattern Name]

• Where Used: [Components/modules using this pattern]
• Implementation: [How it's implemented]
• Benefits: [Why we use it]

Data Architecture

Data Flow

[Diagram showing how data moves through the system]

Storage Strategy

Data Type	Storage	Rationale	Retention
[Type]	[Where stored]	[Why]	[How long]
[Type]	[Where stored]	[Why]	[How long]

Data Models

• Core Entities: [List main domain objects]
• Relationships: [How entities relate]
• Schemas: [Location of schema definitions]

Integration Architecture

Internal Integrations

Service A <--> Service B
   |              |
   v              v
Service C <--> Service D

External Integrations

System	Integration Type	Purpose	Critical?
[Name]	[REST/GraphQL/etc]	[Why we integrate]	[Yes/No]
[Name]	[Type]	[Purpose]	[Yes/No]

API Design Principles

• [Principle 1: e.g., RESTful conventions]
• [Principle 2: e.g., Versioning strategy]
• [Principle 3: e.g., Error handling approach]

Security Architecture

Security Layers

1. Edge Security: [WAF, DDoS protection]
2. Application Security: [Authentication, authorization]
3. Data Security: [Encryption at rest/transit]
4. Infrastructure Security: [Network isolation, secrets]

Authentication & Authorization

• Method: [JWT, OAuth, SAML, etc.]
• Implementation: [How it works]
• Authorization Model: [RBAC, ABAC, etc.]

Critical Implementation Paths

Path 1: [User Authentication Flow]

1. User submits credentials
2. [Step 2 with component]
3. [Step 3 with component]
4. Token returned

Path 2: [Core Business Process]

1. [Starting point]
2. [Processing step]
3. [Decision point]
4. [Completion]

Performance Patterns

Caching Strategy

• What's Cached: [Data types]
• Where: [Cache locations]
• TTL: [Expiration strategies]
• Invalidation: [How cache is cleared]

Async Processing

• Queue System: [Technology used]
• Use Cases: [What goes async]
• Retry Logic: [Failure handling]

Scalability Patterns

Horizontal Scaling

• Stateless Components: [Which can scale out]
• Load Balancing: [Strategy]
• Session Management: [How handled]

Vertical Scaling

• Bottlenecks: [Known limitations]
• Optimization Points: [Where to focus]

Key Technical Decisions

Reference: See docs/adr/ for detailed Architectural Decision Records

Decision 1: [Title]

• Choice: [What was decided]
• Rationale: [Why]
• Impact: [Consequences]

Decision 2: [Title]

• Choice: [What was decided]
• Rationale: [Why]
• Impact: [Consequences]

Error Handling Patterns

Global Error Strategy

• Logging: [How errors are logged]
• User Feedback: [How errors shown to users]
• Recovery: [Automatic recovery mechanisms]

Circuit Breakers

• Protected Services: [Which integrations]
• Thresholds: [When circuits open]
• Fallbacks: [Degraded functionality]

Monitoring & Observability

Key Metrics

• Business Metrics: [What we track]
• Technical Metrics: [Performance indicators]
• SLIs/SLOs: [Service level indicators/objectives]

Logging Strategy

• Log Levels: [When to use each]
• Structured Logging: [Format/fields]
• Retention: [How long kept]

---

This document captures the technical architecture and implementation patterns. It's updated when architectural decisions are made or patterns change.