architecture-selection · diff
git:20251226.8786fb8 to git:20260221.26d502d
116 added, 462 removed. Audit A to A.
---
name: architecture-selection
description: System architecture patterns including monolith, microservices, event-driven, and serverless, with C4 modeling, scalability strategies, and technology selection criteria. Use when designing system architectures, evaluating patterns, or planning scalability.
---
- # Architecture Pattern Selection
-
- Systematic guidance for selecting and implementing architecture patterns that match requirements, team capabilities, and scalability needs.
-
- ## When to Activate
-
- - Designing new system architectures
- - Evaluating monolith vs microservices vs serverless
- - Planning scalability strategies
- - Selecting technology stacks
- - Creating architecture documentation
- - Reviewing architecture decisions
-
- ## Architecture Patterns
-
- ### Monolithic Architecture
-
- A single deployable unit containing all functionality.
-
- ```
- ┌─────────────────────────────────────────────────────────────┐
- │ Monolithic Application │
- ├─────────────────────────────────────────────────────────────┤
- │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
- │ │ Web UI │ │ API Layer │ │ Admin UI │ │
- │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
- │ │ │ │ │
- │ └────────────────┼────────────────┘ │
- │ │ │
- │ ┌───────────────────────┴───────────────────────────┐ │
- │ │ Business Logic Layer │ │
- │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
- │ │ │ Orders │ │ Users │ │ Products │ │ │
- │ │ └──────────┘ └──────────┘ └──────────┘ │ │
- │ └───────────────────────┬───────────────────────────┘ │
- │ │ │
- │ ┌───────────────────────┴───────────────────────────┐ │
- │ │ Data Access Layer │ │
- │ └───────────────────────┬───────────────────────────┘ │
- │ │ │
- └──────────────────────────┼──────────────────────────────────┘
- │
- ┌──────┴──────┐
- │ Database │
- └─────────────┘
- ```
-
- **When to Use:**
- - Small team (< 10 developers)
- - Simple domain
- - Rapid iteration needed
- - Limited infrastructure expertise
-
- **Trade-offs:**
-
- | Pros | Cons |
- |------|------|
- | Simple deployment | Limited scalability |
- | Easy debugging | Large codebase to manage |
- | Single codebase | Technology lock-in |
- | Fast development initially | Team coupling |
- | Transactional consistency | Full redeploy for changes |
-
- ### Microservices Architecture
-
- Independently deployable services organized around business capabilities.
-
- ```
- ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
- │ Web UI │ │Mobile │ │ Admin │ │External│
- └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
- │ │ │ │
- └────────────┴────────────┴────────────┘
- │
- ┌────────┴────────┐
- │ API Gateway │
- └────────┬────────┘
- │
- ┌──────────────────┼──────────────────┐
- │ │ │
- ┌───┴───┐ ┌────┴───┐ ┌───┴───┐
- │ Order │ │ User │ │Product│
- │Service│ │Service │ │Service│
- ├───────┤ ├────────┤ ├───────┤
- │ DB │ │ DB │ │ DB │
- └───────┘ └────────┘ └───────┘
- │ │ │
- └──────────────────┴──────────────────┘
- │
- ┌────────┴────────┐
- │ Message Bus │
- └─────────────────┘
- ```
-
- **When to Use:**
- - Large team (> 20 developers)
- - Complex, evolving domain
- - Independent scaling needed
- - Different tech stacks for different services
- - High availability requirements
-
- **Trade-offs:**
-
- | Pros | Cons |
- |------|------|
- | Independent deployment | Operational complexity |
- | Technology flexibility | Network latency |
- | Team autonomy | Distributed debugging |
- | Targeted scaling | Data consistency challenges |
- | Fault isolation | More infrastructure |
-
- ### Event-Driven Architecture
-
- Services communicate through events rather than direct calls.
-
- ```
- ┌─────────────────────────────────────────────────────────────┐
- │ Event Bus / Broker │
- ├─────────────────────────────────────────────────────────────┤
- │ │
- │ OrderPlaced UserCreated PaymentReceived │
- │ │
- └──────┬──────────────┬──────────────┬───────────────────────┘
- │ │ │
- ▼ ▼ ▼
- ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
- │ Order │ │ User │ │ Payment │
- │ Service │ │ Service │ │ Service │
- │ │ │ │ │ │
- │ Publishes: │ │ Publishes: │ │ Publishes: │
- │ OrderPlaced │ │ UserCreated │ │ PaymentRcvd │
- │ │ │ │ │ │
- │ Subscribes: │ │ Subscribes: │ │ Subscribes: │
- │ PaymentRcvd │ │ OrderPlaced │ │ OrderPlaced │
- └─────────────┘ └─────────────┘ └─────────────┘
- ```
-
- **When to Use:**
- - Loose coupling required
- - Asynchronous processing acceptable
- - Complex workflows spanning multiple services
- - Audit trail needed
- - Event sourcing scenarios
-
- **Trade-offs:**
-
- | Pros | Cons |
- |------|------|
- | Temporal decoupling | Eventual consistency |
- | Natural audit log | Complex debugging |
- | Scalability | Message ordering challenges |
- | Extensibility | Infrastructure requirements |
- | Resilience | Learning curve |
-
- ### Serverless Architecture
-
- Functions executed on-demand without managing servers.
-
- ```
- ┌────────────────────────────────────────────────────────────┐
- │ Client │
- └────────────────────────────┬───────────────────────────────┘
- │
- ┌────────────────────────────┴───────────────────────────────┐
- │ API Gateway │
- └────────────────────────────┬───────────────────────────────┘
- │
- ┌────────────────────────┼────────────────────────┐
- │ │ │
- ▼ ▼ ▼
- ┌──────────┐ ┌──────────┐ ┌──────────┐
- │ Function │ │ Function │ │ Function │
- │ GetUser │ │CreateOrder│ │ SendEmail│
- └────┬─────┘ └────┬─────┘ └────┬─────┘
- │ │ │
- ▼ ▼ ▼
- ┌──────────┐ ┌──────────┐ ┌──────────┐
- │ Database │ │ Queue │ │ Email │
- │ │ │ │ │ Service │
- └──────────┘ └──────────┘ └──────────┘
- ```
-
- **When to Use:**
- - Variable/unpredictable workloads
- - Event-triggered processing
- - Cost optimization for low traffic
- - Rapid development needed
- - Short-running operations
-
- **Trade-offs:**
-
- | Pros | Cons |
- |------|------|
- | No server management | Cold start latency |
- | Pay-per-use | Execution time limits |
- | Auto-scaling | Vendor lock-in |
- | Rapid deployment | Complex local development |
- | Reduced ops burden | Stateless constraints |
-
- ### Pattern Selection Guide
-
- | Factor | Monolith | Microservices | Event-Driven | Serverless |
- |--------|----------|---------------|--------------|------------|
- | Team Size | Small (<10) | Large (>20) | Any | Any |
- | Domain Complexity | Simple | Complex | Complex | Simple-Medium |
- | Scaling Needs | Uniform | Varied | Async | Unpredictable |
- | Time to Market | Fast initially | Slower start | Medium | Fast |
- | Ops Maturity | Low | High | High | Medium |
-
- ## C4 Model
-
- Hierarchical way to document architecture at multiple levels of detail.
-
- ### Level 1: System Context
-
- Shows system in its environment with external actors and systems.
-
- ```
- ┌──────────────────────────────────────────────────────────────┐
- │ System Context Diagram │
- ├──────────────────────────────────────────────────────────────┤
- │ │
- │ ┌──────────┐ ┌──────────┐ │
- │ │ Customer │ │ Admin │ │
- │ │ [User] │ │ [User] │ │
- │ └────┬─────┘ └────┬─────┘ │
- │ │ │ │
- │ │ Places orders │ Manages │
- │ │ │ products │
- │ ▼ ▼ │
- │ ┌────────────────────────────────────────────────┐ │
- │ │ E-Commerce System │ │
- │ │ [Software System] │ │
- │ └───────────┬─────────────────┬──────────────────┘ │
- │ │ │ │
- │ │ │ │
- │ ▼ ▼ │
- │ ┌───────────────┐ ┌───────────────┐ │
- │ │ Payment │ │ Email │ │
- │ │ Gateway │ │ Provider │ │
- │ │ [External] │ │ [External] │ │
- │ └───────────────┘ └───────────────┘ │
- │ │
- └──────────────────────────────────────────────────────────────┘
- ```
-
- ### Level 2: Container
-
- Shows the high-level technology choices and how containers communicate.
-
- ```
- ┌──────────────────────────────────────────────────────────────┐
- │ Container Diagram │
- ├──────────────────────────────────────────────────────────────┤
- │ │
- │ ┌──────────────────┐ ┌──────────────────┐ │
- │ │ Web App │ │ Mobile App │ │
- │ │ [React SPA] │ │ [React Native] │ │
- │ └────────┬─────────┘ └────────┬─────────┘ │
- │ │ │ │
- │ │ HTTPS │ │
- │ └───────────┬───────────────┘ │
- │ ▼ │
- │ ┌───────────────────────┐ │
- │ │ API Gateway │ │
- │ │ [Kong] │ │
- │ └───────────┬───────────┘ │
- │ │ │
- │ ┌────────────────┼────────────────┐ │
- │ │ │ │ │
- │ ▼ ▼ ▼ │
- │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
- │ │ Order │ │ User │ │ Product │ │
- │ │ Service │ │ Service │ │ Service │ │
- │ │ [Node] │ │ [Node] │ │ [Go] │ │
- │ └────┬────┘ └────┬────┘ └────┬────┘ │
- │ │ │ │ │
- │ ▼ ▼ ▼ │
- │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
- │ │ Orders │ │ Users │ │Products │ │
- │ │ DB │ │ DB │ │ DB │ │
- │ │[Postgres│ │[Postgres│ │ [Mongo] │ │
- │ └─────────┘ └─────────┘ └─────────┘ │
- │ │
- └──────────────────────────────────────────────────────────────┘
- ```
-
- ### Level 3: Component
-
- Shows internal structure of a container.
-
- ```
- ┌──────────────────────────────────────────────────────────────┐
- │ Component Diagram: Order Service │
- ├──────────────────────────────────────────────────────────────┤
- │ │
- │ ┌───────────────────────────────────────────────────────┐ │
- │ │ API Layer │ │
- │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
- │ │ │ OrdersCtrl │ │ HealthCtrl │ │ MetricsCtrl │ │ │
- │ │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
- │ └─────────┼─────────────────────────────────────────────┘ │
- │ │ │
- │ ┌─────────┼─────────────────────────────────────────────┐ │
- │ │ ▼ Domain Layer │ │
- │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
- │ │ │OrderService │ │ OrderCalc │ │ Validators │ │ │
- │ │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
- │ └─────────┼─────────────────────────────────────────────┘ │
- │ │ │
- │ ┌─────────┼─────────────────────────────────────────────┐ │
- │ │ ▼ Infrastructure Layer │ │
- │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
- │ │ │ OrderRepo │ │PaymentClient│ │ EventPub │ │ │
- │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
- │ └───────────────────────────────────────────────────────┘ │
- │ │
- └──────────────────────────────────────────────────────────────┘
- ```
-
- ### Level 4: Code
-
- Shows implementation details (class diagrams, sequence diagrams).
-
- *Use standard UML when needed at this level.*
-
- ## Scalability Patterns
-
- ### Horizontal Scaling
-
- Add more instances of the same component.
-
- ```
- Load Balancer
- │
- ┌───────────────┼───────────────┐
- │ │ │
- ▼ ▼ ▼
- ┌─────────┐ ┌─────────┐ ┌─────────┐
- │Instance │ │Instance │ │Instance │
- │ 1 │ │ 2 │ │ 3 │
- └─────────┘ └─────────┘ └─────────┘
-
- Requirements:
- - Stateless services
- - Shared session storage
- - Database can handle connections
- ```
-
- ### Caching
-
- Reduce load on slow resources.
-
- ```
- ┌─────────────────────────────────────────────────────┐
- │ Caching Layers │
- ├─────────────────────────────────────────────────────┤
- │ │
- │ Browser Cache → CDN → App Cache → Database Cache │
- │ │
- │ Examples: │
- │ - Browser: Static assets, API responses │
- │ - CDN: Static content, cached API responses │
- │ - App: Redis/Memcached for sessions, computed data│
- │ - Database: Query cache, connection pooling │
- │ │
- └─────────────────────────────────────────────────────┘
-
- Cache Invalidation Strategies:
- - TTL (Time to Live): Simplest, eventual consistency
- - Write-through: Update cache on write
- - Write-behind: Async update for performance
- - Cache-aside: App manages cache explicitly
- ```
+ ## Persona
- ### Database Scaling
+ Act as a system architecture advisor who guides teams in selecting and implementing architecture patterns matched to their requirements, team capabilities, and scalability needs. You balance pragmatism with forward-thinking design.
- | Strategy | Use Case | Trade-off |
- |----------|----------|-----------|
- | **Read Replicas** | Read-heavy workloads | Replication lag |
- | **Sharding** | Large datasets | Query complexity |
- | **Partitioning** | Time-series data | Partition management |
- | **CQRS** | Different read/write patterns | System complexity |
+ **Architecture Target**: $ARGUMENTS
- ### Reliability Patterns
+ ## Interface
- | Pattern | Purpose | Implementation |
- |---------|---------|----------------|
- | **Circuit Breaker** | Prevent cascade failures | Fail fast after threshold |
- | **Bulkhead** | Isolate failures | Separate thread pools |
- | **Retry** | Handle transient failures | Exponential backoff |
- | **Timeout** | Bound wait times | Don't wait forever |
- | **Rate Limiting** | Prevent overload | Throttle requests |
+ EvaluationCriteria {
+ teamSize: String // e.g., "< 10", "> 20"
+ domainComplexity: SIMPLE | MEDIUM | COMPLEX
+ scalingNeeds: UNIFORM | VARIED | ASYNC | UNPREDICTABLE
+ opsMaturity: LOW | MEDIUM | HIGH
+ timeToMarket: FAST | MEDIUM | SLOW
+ }
- ```
- Circuit Breaker States:
+ ArchitectureRecommendation {
+ pattern: MONOLITH | MICROSERVICES | EVENT_DRIVEN | SERVERLESS | HYBRID
+ rationale: String
+ tradeoffs: String
+ migrationPath: String
+ }
- ┌────────┐
- │ CLOSED │ ──── Failure Threshold ──► ┌────────┐
- │(normal)│ │ OPEN │
- └────────┘ │(failing│
- ▲ └────┬───┘
- │ │
- Success Timeout
- Threshold │
- │ ▼
- ┌────┴────┐ ┌─────────┐
- │HALF-OPEN│ ◄─── Test Request ────── │ │
- └─────────┘ └─────────┘
- ```
+ TechnologyScore {
+ name: String
+ fit: Number // 1-5
+ maturity: Number // 1-5
+ teamSkills: Number // 1-5
+ performance: Number // 1-5
+ operations: Number // 1-5
+ cost: Number // 1-5
+ weighted: Number // calculated
+ }
- ## Technology Selection
+ fn gatherRequirements(target)
+ fn evaluatePatterns(criteria)
+ fn selectArchitecture(evaluation)
+ fn documentDecision(recommendation)
+ fn recommendNextSteps(decision)
- ### Selection Criteria
+ ## Constraints
- | Criterion | Questions |
- |-----------|-----------|
- | **Fit** | Does it solve the actual problem? |
- | **Maturity** | Production-proven? Community size? |
- | **Team Skills** | Can the team use it effectively? |
- | **Performance** | Meets requirements? Benchmarks? |
- | **Operations** | How hard to deploy, monitor, debug? |
- | **Cost** | License, infrastructure, learning curve? |
- | **Lock-in** | Exit strategy? Standards compliance? |
- | **Security** | Track record? Compliance certifications? |
+ Constraints {
+ require {
+ Evaluate at least 2 candidate patterns before recommending.
+ Document trade-offs for every recommendation.
+ Consider team capabilities and ops maturity, not just technical fit.
+ Provide a migration path from current state when applicable.
+ Use ADR format for architecture decisions.
+ }
+ never {
+ Recommend patterns based on resume-driven development (choosing tech for experience).
+ Skip trade-off analysis for any recommendation.
+ Assume microservices are always better than monoliths.
+ Ignore operational complexity when evaluating patterns.
+ Recommend scaling before measuring actual bottlenecks.
+ }
+ }
- ### Evaluation Matrix
+ ## State
- ```
- | Technology | Fit | Maturity | Skills | Perf | Ops | Cost | Score |
- |------------|-----|----------|--------|------|-----|------|-------|
- | Option A | 4 | 5 | 3 | 4 | 4 | 3 | 3.8 |
- | Option B | 5 | 3 | 4 | 5 | 2 | 4 | 3.8 |
- | Option C | 3 | 4 | 5 | 3 | 5 | 5 | 4.2 |
+ State {
+ target = $ARGUMENTS
+ criteria: EvaluationCriteria // gathered in gatherRequirements
+ candidates: [ArchitectureRecommendation] // evaluated in evaluatePatterns
+ selected: ArchitectureRecommendation // chosen in selectArchitecture
+ technologies: [TechnologyScore] // scored in selectArchitecture
+ }
- Weights: Fit(25%), Maturity(15%), Skills(20%), Perf(15%), Ops(15%), Cost(10%)
- ```
+ ## Reference Materials
- ## Architecture Decision Records (ADRs)
+ See `reference/` directory for detailed patterns:
+ - [Architecture Patterns](reference/architecture-patterns.md) — Monolith, microservices, event-driven, serverless with diagrams and trade-offs
+ - [C4 Model](reference/c4-model.md) — System context, container, component, and code level diagrams
+ - [Scalability and Reliability](reference/scalability-and-reliability.md) — Horizontal scaling, caching, database scaling, circuit breakers
- ### ADR Template
+ ## Workflow
- ```markdown
- # ADR-[NUMBER]: [TITLE]
+ fn gatherRequirements(target) {
+ Analyze target context for:
+ - Team size and structure
+ - Domain complexity and bounded contexts
+ - Scaling requirements (read/write patterns, peak loads)
+ - Operational maturity (CI/CD, monitoring, on-call)
+ - Time-to-market pressure
+ - Existing infrastructure and constraints
- ## Status
- [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+ Build EvaluationCriteria from gathered information.
+ }
- ## Context
- [What is the issue we're facing? What decision needs to be made?]
+ fn evaluatePatterns(criteria) {
+ SELECTION GUIDE:
- ## Decision
- [What is the change we're proposing/making?]
+ | Factor | Monolith | Microservices | Event-Driven | Serverless |
+ |--------|----------|---------------|--------------|------------|
+ | Team Size | Small (<10) | Large (>20) | Any | Any |
+ | Domain Complexity | Simple | Complex | Complex | Simple-Medium |
+ | Scaling Needs | Uniform | Varied | Async | Unpredictable |
+ | Time to Market | Fast initially | Slower start | Medium | Fast |
+ | Ops Maturity | Low | High | High | Medium |
- ## Consequences
- ### Positive
- - [Benefit 1]
- - [Benefit 2]
+ Load reference/architecture-patterns.md for detailed pattern analysis.
- ### Negative
- - [Trade-off 1]
- - [Trade-off 2]
+ Score each candidate pattern against criteria.
+ Identify anti-patterns to avoid:
+ - Big Ball of Mud — no clear architecture => establish bounded contexts
+ - Distributed Monolith — microservices without independence => true service boundaries
+ - Premature Optimization — scaling before needed => start simple, measure, scale
+ - Golden Hammer — same solution for every problem => evaluate each case
+ - Ivory Tower — architecture divorced from reality => evolutionary architecture
+ }
- ### Neutral
- - [Observation]
+ fn selectArchitecture(evaluation) {
+ Select highest-scoring pattern with migration feasibility.
- ## Alternatives Considered
- ### Alternative 1: [Name]
- - Pros: [...]
- - Cons: [...]
- - Why rejected: [...]
- ```
+ For technology selection, use weighted evaluation matrix:
+ Weights: Fit(25%), Maturity(15%), Skills(20%), Perf(15%), Ops(15%), Cost(10%)
- ## Anti-Patterns
+ Load reference/c4-model.md when creating architecture documentation.
+ Load reference/scalability-and-reliability.md when detailing scaling strategy.
+ }
- | Anti-Pattern | Problem | Solution |
- |--------------|---------|----------|
- | **Big Ball of Mud** | No clear architecture | Establish bounded contexts |
- | **Distributed Monolith** | Microservices without independence | True service boundaries |
- | **Resume-Driven** | Choosing tech for experience | Match tech to requirements |
- | **Premature Optimization** | Scaling before needed | Start simple, measure, scale |
- | **Ivory Tower** | Architecture divorced from reality | Evolutionary architecture |
- | **Golden Hammer** | Same solution for every problem | Evaluate each case |
+ fn documentDecision(recommendation) {
+ ADR TEMPLATE:
+ Status — Proposed | Accepted | Deprecated | Superseded
+ Context — What decision needs to be made and why
+ Decision — The selected architecture with rationale
+ Consequences — Positive, negative, and neutral impacts
+ Alternatives Considered — Each with pros, cons, and rejection reason
+ }
- ## References
+ fn recommendNextSteps(decision) {
+ match (decision) {
+ new system => Create C4 diagrams, define bounded contexts, plan infrastructure
+ migration => Define incremental migration plan with rollback strategy
+ review => List specific improvements with trade-off analysis
+ }
+ }
- - [Pattern Examples](examples/architecture-patterns.md) - Detailed implementations
- - [ADR Repository](examples/adrs/) - Example decision records
+ architectureSelection(target) {
+ gatherRequirements(target) |> evaluatePatterns |> selectArchitecture |> documentDecision |> recommendNextSteps
+ }