majiayu000 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 | modern-patterns.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 | event-driven-template.md | Multi-service transactions |
| Plan observability | SLIs/SLOs/SLAs, Distributed tracing, Metrics, Logs | architecture-blueprint.md | Production readiness |
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
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.
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
- 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 Relevant)
For ecosystem-sensitive questions (current vendor constraints, shifting best practices), use data/sources.json as the starting index:
- 2026 trends overview:
references/architecture-trends-2026.md - Platform engineering / IDPs:
.platform_engineering_2026 - Data mesh and analytics architecture:
.scalability_reliability(data mesh entries) - AI-native systems (RAG, agents, MCP/A2A):
.optional_ai_architecture
If fresh web access is not available, answer with best-known patterns and explicitly call out assumptions.
Navigation
Core Resources
- references/modern-patterns.md — 10 contemporary architecture patterns with decision trees (microservices, event-driven, serverless, CQRS, modular monolith, service mesh, edge computing)
- references/scalability-reliability-guide.md — CAP theorem, database scaling, caching strategies, circuit breakers, SRE patterns, observability
- references/architecture-trends-2026.md — Platform engineering, data mesh, AI-native systems (load only when relevant)
- data/sources.json — 60 curated external resources (AWS, Azure, Google Cloud, Martin Fowler, microservices.io, SRE books, multi-agent patterns, MCP/A2A protocols, platform engineering 2026)
Templates
Planning & Documentation (assets/planning/):
- assets/planning/architecture-blueprint.md — Service blueprint template (dependencies, SLAs, data flows, resilience, security, observability)
- assets/planning/adr-template.md — Architecture Decision Record (ADR) for documenting design decisions with tradeoff analysis
Architecture Patterns (assets/patterns/):
- assets/patterns/microservices-template.md — Complete microservices design template (API contracts, resilience, deployment, testing, cost optimization)
- assets/patterns/event-driven-template.md — Event-driven architecture template (event schemas, saga patterns, event sourcing, schema evolution)
Operations & Scalability (assets/operations/):
- assets/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:
- ../ops-devops-platform/SKILL.md — CI/CD, deployment strategies, IaC, platform operations
- ../qa-observability/SKILL.md — Monitoring, tracing, alerting, SLOs
Security & Data:
- ../software-security-appsec/SKILL.md — Threat modeling, authentication, authorization, secure design
- ../data-sql-optimization/SKILL.md — Database design, optimization, indexing strategies
Quality & Code:
- ../software-code-review/SKILL.md — Code review practices, architectural review
Documentation:
- ../docs-codebase/SKILL.md — Architecture documentation, C4 diagrams, ADRs
Freshness Protocol (When the Question Depends on "Now")
Use this when the user is asking for current best practices, vendor-specific constraints, or trend-sensitive recommendations.
- If live web access is available, consult 2–3 authoritative sources from
data/sources.json(cloud frameworks, SRE, pattern catalogs) and fold new constraints into the recommendation. - If live web access is not available, answer with durable patterns and explicitly state assumptions that could change (vendor limits, pricing, managed-service capabilities, ecosystem maturity).
Operational Playbooks
Shared Foundation
- ../software-clean-code-standard/references/clean-code-standard.md - Canonical clean code rules (
CC-*) for citation - Legacy playbook: ../software-clean-code-standard/references/code-quality-operational-playbook.md -
RULE-01–RULE-13, operational procedures, and design patterns - ../software-clean-code-standard/references/design-patterns-operational-checklist.md - GoF pattern triggers and guardrails, when to apply vs avoid patterns
Architecture-Specific
- references/operational-playbook.md — Detailed architecture questions, decomposition patterns, security layers, and external references