Software Architecture Design — Quick Reference

Use this skill for system-level design decisions rather than implementation details within a single service or component.

Quick Reference

When to Use This Skill

Invoke when working on:

• System decomposition: Deciding between monolith, modular monolith, microservices
• Architecture patterns: Event-driven, CQRS, layered, hexagonal, serverless
• Data architecture: Consistency models, sharding, replication, CQRS patterns
• Scalability design: Load balancing, caching strategies, database scaling
• Resilience patterns: Circuit breakers, retries, bulkheads, graceful degradation
• API contracts: Service boundaries, versioning, integration patterns
• Architecture decisions: ADRs, tradeoff analysis, technology selection

Decision Tree: Choosing Architecture Pattern

Project needs: [New System or Major Refactor]
    ├─ Single team, evolving domain?
    │   ├─ Start simple → Modular Monolith (clear module boundaries)
    │   └─ Need rapid iteration → Layered Architecture
    │
    ├─ Multiple teams, clear bounded contexts?
    │   ├─ Independent deployment critical → Microservices
    │   └─ Shared data model → Modular Monolith with service modules
    │
    ├─ Event-driven workflows?
    │   ├─ Asynchronous processing → Event-Driven Architecture (Kafka, queues)
    │   └─ Complex state machines → Saga pattern + Event Sourcing
    │
    ├─ Variable/unpredictable load?
    │   ├─ Pay-per-use model → Serverless (AWS Lambda, Cloudflare Workers)
    │   └─ Batch processing → Serverless + queues
    │
    └─ High consistency requirements?
        ├─ Strong ACID guarantees → Monolith or Modular Monolith
        └─ Distributed data → CQRS + Event Sourcing

Decision Factors:

• Team size and structure (Conway's Law)
• Deployment independence needs
• Consistency vs availability tradeoffs (CAP theorem)
• Operational maturity (monitoring, orchestration)

See resources/modern-patterns.md for detailed pattern descriptions.

Navigation

Core Resources

• resources/modern-patterns.md — 10 contemporary architecture patterns with decision trees (microservices, event-driven, serverless, CQRS, modular monolith, service mesh, edge computing)
• resources/scalability-reliability-guide.md — CAP theorem, database scaling, caching strategies, circuit breakers, SRE patterns, observability
• data/sources.json — 42 curated external resources (AWS, Azure, Google Cloud, Martin Fowler, microservices.io, SRE books, 2024-2025 best practices)

Templates

Planning & Documentation (templates/planning/):

• templates/planning/architecture-blueprint.md — Service blueprint template (dependencies, SLAs, data flows, resilience, security, observability)
• templates/planning/adr-template.md — Architecture Decision Record (ADR) for documenting design decisions with tradeoff analysis

Architecture Patterns (templates/patterns/):

• templates/patterns/microservices-template.md — Complete microservices design template (API contracts, resilience, deployment, testing, cost optimization)
• templates/patterns/event-driven-template.md — Event-driven architecture template (event schemas, saga patterns, event sourcing, schema evolution)

Operations & Scalability (templates/operations/):

• templates/operations/scalability-checklist.md — Comprehensive scalability checklist (database scaling, caching, load testing, auto-scaling, DR)

Related Skills

Implementation Details:

• ../software-backend/SKILL.md — Backend engineering, API implementation, data layer
• ../software-frontend/SKILL.md — Frontend architecture, micro-frontends, state management
• ../dev-api-design/SKILL.md — REST, GraphQL, gRPC design patterns

Reliability & Operations:

Security & Data:

• ../software-security-appsec/SKILL.md — Threat modeling, authentication, authorization, secure design

Quality & Code:

• ../software-code-review/SKILL.md — Code review practices, architectural review

Documentation:

• ../docs-codebase/SKILL.md — Architecture documentation, C4 diagrams, ADRs

Operational Playbooks

Shared Foundation

• ../../_shared/resources/code-quality-operational-playbook.md — Canonical coding rules (RULE-01 to RULE-13), Section 6: Design Patterns & Application Rules (Strategy, Adapter, Repository, Observer, CQRS)
• ../../_shared/resources/design-patterns-operational-checklist.md — GoF pattern triggers and guardrails, when to apply vs avoid patterns

Architecture-Specific

• resources/operational-playbook.md — Detailed architecture questions, decomposition patterns, security layers, and external references