Software Architecture Reference
An encyclopedia of 137 in-depth architecture articles. Each article is 3,000-5,000 words covering the problem, core concept, real-world practices (Google, AWS, Microsoft), implementation guidance, trade-offs, common mistakes, and connections to other patterns.
Scripts
SA="${CLAUDE_PLUGIN_ROOT}/scripts"
Commands
Search — Find patterns by meaning
npx tsx "$SA/search-patterns.ts" "<natural language query>" --top 5 --json
Examples:
"how to handle database failures gracefully""scaling read-heavy workloads""breaking apart a legacy system""ensuring data consistency across services"
The search uses semantic embeddings — it understands meaning, not just keywords.
List — Browse the catalog
bash "$SA/list-patterns.sh" # All 137 patterns by volume
bash "$SA/list-patterns.sh" --volume 4 # Volume 4: Resilience
bash "$SA/list-patterns.sh" --search "event" # Keyword filter
bash "$SA/list-patterns.sh" --count # Quick count
Read — Full article
After finding a pattern via search or list, read the full article:
${CLAUDE_PLUGIN_ROOT}/volume-NN-name/pattern-name.md
Always read the full article. These are not summaries — they are comprehensive guides with real-world examples, implementation details, and trade-off analysis.
Compare — Side by side
bash "$SA/compare-patterns.sh" "circuit-breaker" "bulkhead"
bash "$SA/compare-patterns.sh" "microservices" "modular-monolith" "service-based"
Related — Find connected patterns
After reading an article, check its "Connections" section for related patterns. Then read those for a complete picture.
Common pattern clusters:
- Resilience stack: circuit-breaker + bulkhead + timeout-patterns + retry + load-shedding
- Event-driven stack: event-driven + event-sourcing + cqrs + publisher-subscriber + saga
- DDD stack: bounded-context + aggregates + domain-events + context-mapping + ubiquitous-language
- API stack: resource-oriented-design + api-versioning + api-idempotency + consumer-driven-contracts
- Scale stack: sharding + partitioning + cache-aside + competing-consumers + materialized-view
- Operations stack: sre-principles + slo-sli-sla + observability + safe-deployments + chaos-engineering
- Modern stack: modular-monolith + hexagonal + vertical-slice + architecture-decision-records + fitness-functions
Volumes
| # |
Volume |
Articles |
Topics |
| 01 |
Foundations |
12 |
Complexity, trade-offs, boundaries, deep modules, cognitive load, fitness functions, ADRs |
| 02 |
Architecture Styles |
10 |
Layered, modular monolith, microservices, event-driven, service-based, hexagonal, vertical slice |
| 03 |
Cloud Design Patterns |
25 |
Ambassador, bulkhead, CQRS, circuit breaker, saga, sidecar, strangler fig, and 18 more |
| 04 |
Resilience & Reliability |
15 |
Error budgets, timeouts, backoff, load shedding, shuffle sharding, cell-based, chaos engineering |
| 05 |
Data Architecture |
15 |
Replication, partitioning, consistency models, CAP, consensus, streaming, CDC, transactions |
| 06 |
Domain-Driven Design |
12 |
Ubiquitous language, bounded context, aggregates, domain events, context mapping, repositories |
| 07 |
API & Integration |
10 |
REST, gRPC, versioning, pagination, idempotency, contracts, gateway, service mesh |
| 08 |
Distributed Systems |
12 |
Fallacies, consistent hashing, quorum, CRDT, gossip, clocks, split brain, exactly-once |
| 09 |
Operations & Delivery |
12 |
SRE, SLOs, observability, deployment strategies, feature flags, platform engineering, GitOps |
| 10 |
Modern Paradigms |
14 |
Data mesh, AI-native, edge computing, zero trust, serverless, actor model, WebAssembly |
Usage Guidelines
- For quick lookups: Search → Read the specific section you need
- For learning a topic: List a volume → Read articles in order (they build on each other)
- For decision-making: Use the
aio-architect-advisor skill instead — it provides a guided workflow
- For comparing options: Use the compare command or read both articles and cross-reference their trade-off sections
1---2name: aio-architect-reference3description: Look up architecture patterns and concepts via semantic search — read the full article on demand, compare patterns side-by-side, or browse by volume.4---56# Software Architecture Reference78An encyclopedia of 137 in-depth architecture articles. Each article is 3,000-5,000 words covering the problem, core concept, real-world practices (Google, AWS, Microsoft), implementation guidance, trade-offs, common mistakes, and connections to other patterns.910## Scripts1112```bash13SA="${CLAUDE_PLUGIN_ROOT}/scripts"14```1516## Commands1718### Search — Find patterns by meaning1920```bash21npx tsx "$SA/search-patterns.ts" "<natural language query>" --top 5 --json22```2324Examples:25- `"how to handle database failures gracefully"`26- `"scaling read-heavy workloads"`27- `"breaking apart a legacy system"`28- `"ensuring data consistency across services"`2930The search uses semantic embeddings — it understands meaning, not just keywords.3132### List — Browse the catalog3334```bash35bash "$SA/list-patterns.sh" # All 137 patterns by volume36bash "$SA/list-patterns.sh" --volume 4 # Volume 4: Resilience37bash "$SA/list-patterns.sh" --search "event" # Keyword filter38bash "$SA/list-patterns.sh" --count # Quick count39```4041### Read — Full article4243After finding a pattern via search or list, read the full article:4445```46${CLAUDE_PLUGIN_ROOT}/volume-NN-name/pattern-name.md47```4849**Always read the full article.** These are not summaries — they are comprehensive guides with real-world examples, implementation details, and trade-off analysis.5051### Compare — Side by side5253```bash54bash "$SA/compare-patterns.sh" "circuit-breaker" "bulkhead"55bash "$SA/compare-patterns.sh" "microservices" "modular-monolith" "service-based"56```5758### Related — Find connected patterns5960After reading an article, check its "Connections" section for related patterns. Then read those for a complete picture.6162Common pattern clusters:63- **Resilience stack**: circuit-breaker + bulkhead + timeout-patterns + retry + load-shedding64- **Event-driven stack**: event-driven + event-sourcing + cqrs + publisher-subscriber + saga65- **DDD stack**: bounded-context + aggregates + domain-events + context-mapping + ubiquitous-language66- **API stack**: resource-oriented-design + api-versioning + api-idempotency + consumer-driven-contracts67- **Scale stack**: sharding + partitioning + cache-aside + competing-consumers + materialized-view68- **Operations stack**: sre-principles + slo-sli-sla + observability + safe-deployments + chaos-engineering69- **Modern stack**: modular-monolith + hexagonal + vertical-slice + architecture-decision-records + fitness-functions7071## Volumes7273| # | Volume | Articles | Topics |74|---|--------|----------|--------|75| 01 | Foundations | 12 | Complexity, trade-offs, boundaries, deep modules, cognitive load, fitness functions, ADRs |76| 02 | Architecture Styles | 10 | Layered, modular monolith, microservices, event-driven, service-based, hexagonal, vertical slice |77| 03 | Cloud Design Patterns | 25 | Ambassador, bulkhead, CQRS, circuit breaker, saga, sidecar, strangler fig, and 18 more |78| 04 | Resilience & Reliability | 15 | Error budgets, timeouts, backoff, load shedding, shuffle sharding, cell-based, chaos engineering |79| 05 | Data Architecture | 15 | Replication, partitioning, consistency models, CAP, consensus, streaming, CDC, transactions |80| 06 | Domain-Driven Design | 12 | Ubiquitous language, bounded context, aggregates, domain events, context mapping, repositories |81| 07 | API & Integration | 10 | REST, gRPC, versioning, pagination, idempotency, contracts, gateway, service mesh |82| 08 | Distributed Systems | 12 | Fallacies, consistent hashing, quorum, CRDT, gossip, clocks, split brain, exactly-once |83| 09 | Operations & Delivery | 12 | SRE, SLOs, observability, deployment strategies, feature flags, platform engineering, GitOps |84| 10 | Modern Paradigms | 14 | Data mesh, AI-native, edge computing, zero trust, serverless, actor model, WebAssembly |8586## Usage Guidelines8788- **For quick lookups**: Search → Read the specific section you need89- **For learning a topic**: List a volume → Read articles in order (they build on each other)90- **For decision-making**: Use the `aio-architect-advisor` skill instead — it provides a guided workflow91- **For comparing options**: Use the compare command or read both articles and cross-reference their trade-off sections
aiocean