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

Task Pattern/Tool Key Resources When to Use

Choose architecture style Layered, Microservices, Event-driven, Serverless modern-patterns.md Greenfield projects, major refactors

Design for scale Load balancing, Caching, Sharding, Read replicas scalability-reliability-guide.md High-traffic systems, performance goals

Ensure resilience Circuit breakers, Retries, Bulkheads, Graceful degradation scalability-reliability-guide.md Distributed systems, external dependencies

Document decisions Architecture Decision Record (ADR) adr-template.md Major technical decisions, tradeoff analysis

Define service boundaries Domain-Driven Design (DDD), Bounded contexts microservices-template.md Microservices decomposition

Model data consistency ACID vs BASE, Event sourcing, CQRS, Saga patterns data-architecture-patterns.md Multi-service transactions

Plan observability SLIs/SLOs/SLAs, Distributed tracing, Metrics, Logs architecture-blueprint.md Production readiness

Migrate from monolith Strangler fig, Database decomposition, Shadow traffic migration-modernization-guide.md Legacy modernization

Design inter-service comms API Gateway, Service mesh, BFF pattern api-gateway-service-mesh.md Microservices networking

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.

• Clarify: problem statement, non-goals, constraints, and success metrics

• Capture quality attributes: availability, latency, throughput, durability, consistency, security, compliance, cost

• Propose 2–3 candidate architectures and compare tradeoffs

• Define boundaries: bounded contexts, ownership, APIs/events, integration contracts

• Decide data strategy: storage, consistency model, schema evolution, migrations

• Design for operations: SLOs, failure modes, observability, deployment, DR, incident playbooks

• Call out scope limits: what NOT to build yet, what to defer, what to buy vs build

• 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

2026 Considerations

Load only when the question explicitly involves current trends, vendor-specific constraints, or "what's the latest thinking on X?"

• references/architecture-trends-2026.md — Platform engineering, data mesh, composable architecture, AI-native systems

• data/sources.json — 60 curated resources organized by category:

• platform_engineering_2026 — IDP trends, AI-platform convergence, Backstage

• optional_ai_architecture — RAG patterns, multi-agent design, MCP/A2A protocols

• modern_architecture_2025 — Data mesh, composable architecture, continuous architecture

If live web access is available, consult 2–3 authoritative sources from data/sources.json and fold findings into the recommendation. If not, answer with durable patterns and explicitly state assumptions that could change (vendor limits, pricing, managed-service capabilities).

Navigation

Core References

Read at most 2–3 references per question — pick the ones most relevant to the specific ask. Do not read all of them.

Reference Contents When to Read

modern-patterns.md 10 architecture patterns with decision trees Choosing or comparing patterns

scalability-reliability-guide.md CAP theorem, DB scaling, caching, circuit breakers, SRE Scaling or reliability questions

data-architecture-patterns.md CQRS variants, event sourcing, data mesh, sagas, consistency Data flow across services

migration-modernization-guide.md Strangler fig, DB decomposition, feature flags, risk assessment Refactoring a monolith

api-gateway-service-mesh.md Gateway patterns, service mesh, mTLS, observability Inter-service communication

architecture-trends-2026.md Platform engineering, data mesh, AI-native systems Current trends only

operational-playbook.md Architecture questions framework, decomposition heuristics Design discussion framing

Templates

Planning & Documentation (assets/planning/):

• architecture-blueprint.md — Service blueprint (dependencies, SLAs, data flows, resilience, security, observability)

• adr-template.md — Architecture Decision Record for tradeoff analysis

Architecture Patterns (assets/patterns/):

• microservices-template.md — Microservices design (API contracts, resilience, deployment, testing)

• event-driven-template.md — Event-driven architecture (event schemas, saga patterns, event sourcing)

Operations (assets/operations/):

• scalability-checklist.md — Scalability checklist (DB scaling, caching, load testing, auto-scaling, DR)

Related Skills

• software-backend — Backend engineering, API implementation, data layer

• software-frontend — Frontend architecture, micro-frontends, state management

• dev-api-design — REST, GraphQL, gRPC design patterns

• ops-devops-platform — CI/CD, deployment strategies, IaC

• qa-observability — Monitoring, tracing, alerting, SLOs

• software-security-appsec — Threat modeling, auth, secure design

• data-sql-optimization — Database design, optimization, indexing

• docs-codebase — Architecture documentation, C4 diagrams, ADRs