Software Architecture Design

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
• Migration planning: Monolith decomposition, strangler fig, database separation

When NOT to Use This Skill

Use other skills instead for:

• Single-service implementation (routes, controllers, business logic) → software-backend
• API endpoint design (REST conventions, GraphQL schemas) → dev-api-design
• Security implementation (auth, encryption, OWASP) → software-security-appsec
• Frontend component architecture → software-frontend
• Database query optimization → data-sql-optimization

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 threshold: <10 developers → modular monolith typically outperforms microservices (operational overhead)
• Team structure (Conway's Law) — architecture mirrors org structure
• Deployment independence needs
• Consistency vs availability tradeoffs (CAP theorem)
• Operational maturity (monitoring, orchestration)

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

Output Guidelines

The references in this skill are background knowledge for you — absorb the patterns and present them as your own expertise. Do not cite internal reference file names (e.g., "from data-architecture-patterns.md") in user-facing output. Users don't know these files exist.

Every architecture recommendation should include:

• Concrete technology picks: Name specific technologies (e.g., "Temporal.io for workflow orchestration", "Socket.io with Redis adapter") rather than staying abstract. The user needs to make build decisions, not just understand patterns.
• What NOT to build: Explicitly call out what to defer or avoid. Premature scope is the #1 architecture mistake — help the user avoid it.
• Team and process alignment: How does this architecture map to team structure? What ownership model does it imply? Include CODEOWNERS, deployment ownership, and on-call boundaries where relevant.
• Success metrics: How will the team know the architecture is working? Include measurable indicators (deploy frequency, lead time, error rates, MTTR).
• Focused length: Aim for depth on the 3–5 decisions that matter most rather than exhaustive coverage of every concern. A recommendation that's too long to read is a recommendation that won't be followed.

Workflow (System-Level)

Use this workflow when a user asks for architecture recommendations, decomposition, or major platform decisions.

1. Clarify: problem statement, non-goals, constraints, and success metrics
2. Capture quality attributes: availability, latency, throughput, durability, consistency, security, compliance, cost
3. Propose 2–3 candidate architectures and compare tradeoffs
4. Define boundaries: bounded contexts, ownership, APIs/events, integration contracts
5. Decide data strategy: storage, consistency model, schema evolution, migrations
6. Design for operations: SLOs, failure modes, observability, deployment, DR, incident playbooks
7. Call out scope limits: what NOT to build yet, what to defer, what to buy vs build
8. Document decisions: write ADRs for key tradeoffs and irreversible choices

Preferred deliverables (pick what fits the request):

• Architecture blueprint: assets/planning/architecture-blueprint.md
• Decision record: assets/planning/adr-template.md
• Pattern deep dives: references/modern-patterns.md, references/scalability-reliability-guide.md