| name | nw-architecture-patterns |
| description | Comprehensive architecture patterns, methodologies, quality frameworks, and evaluation methods for solution architects. Load when designing system architecture or selecting patterns. |
| user-invocable | false |
| disable-model-invocation | true |
Architecture Patterns and Methodologies
C4 Model -- Hierarchical Architecture Visualization
Four levels for different audiences:
- System Context: system + users + external systems (stakeholder view)
- Containers: applications, data stores, deployment units (technical overview)
- Components: internal modules within containers (developer view)
- Code: class/module level (optional, often auto-generated)
Notation/tooling independent. Reduces communication overhead, shared visual language across stakeholders.
Hexagonal Architecture (Ports and Adapters)
Isolate business logic from infrastructure through ports (interfaces) and adapters (implementations).
- Ports: technology-agnostic interfaces for external communication
- Primary ports (driving): REST controllers, CLI handlers, message consumers -- inbound
- Secondary ports (driven): DB repos, external service clients, filesystem -- outbound
- Adapters: technology-specific port implementations
Benefits: testability (isolated core) | flexibility (swap infrastructure) | technology independence | maintainability
Testing: unit tests through driving ports, mock driven ports | integration tests with real infrastructure | acceptance tests end-to-end through primary ports
Architectural Pattern Selection
Layered Architecture
Horizontal layers with defined dependencies. Use for: traditional enterprise apps, clear separation. Trade-off: familiar but potential overhead, layer coupling.
Microservices
Independent deployable services per capability. Use for: large teams, component scaling, tech diversity. Trade-off: scalability vs operational complexity. 2025 consensus: "start monolith, evolve when needed." Modular monolith = valid middle ground.
Event-Driven Architecture
Components communicate via events through broker. Use for: real-time, complex processes, loose coupling. Trade-off: scalability/decoupling vs event ordering, debugging.
CQRS + Event Sourcing
Separate read/write models; store events not state. Use for: financial, audit, temporal queries. Trade-off: complete history + independent scaling vs eventual consistency + complexity. NOT for: simple CRUD, strong consistency, inexperienced teams.
Domain-Driven Design (DDD)
Strategic Patterns
- Bounded Context: explicit boundaries for domain model; prevents "single unified model" trap
- Context Mapping: Shared Kernel | Customer/Supplier | Anti-Corruption Layer | Open Host Service
Tactical Patterns
- Aggregates: consistency/transactional boundaries; root = only entry point
- Domain Events: represent occurrences; enable loose coupling between contexts
Identifying Boundaries
Language differences between departments | representation differences | consistency requirements define aggregate boundaries. Bounded contexts often map to microservice boundaries and team ownership.
ISO 25010 Quality Attributes
Eight characteristics:
- Functional Suitability: completeness, correctness, appropriateness
- Performance Efficiency: time behavior, resource utilization, capacity
- Compatibility: coexistence, interoperability
- Usability: learnability, operability, accessibility
- Reliability: maturity, availability, fault tolerance, recoverability
- Security: confidentiality, integrity, non-repudiation, accountability, authenticity
- Maintainability: modularity, reusability, analyzability, modifiability, testability
- Portability: adaptability, installability, replaceability
Trade-offs: Security vs Performance | Scalability vs Consistency (CAP) | Flexibility vs Performance | Usability vs Security
Application: identify priority attributes, define measurable requirements, analyze trade-offs, validate with ATAM.
ATAM (Architecture Trade-off Analysis Method)
Systematic evaluation from SEI/CMU.
Phase 1 - Presentation: business drivers, architecture approaches, design decisions
Phase 2 - Investigation: quality attribute scenarios, evaluate approaches, identify sensitivity/trade-off points
Phase 3 - Testing: prioritize scenarios, analyze top in depth, document risks/non-risks
Key concepts: Sensitivity Point (impacts one attribute) | Trade-off Point (affects multiple attributes) | Architectural Risk (may prevent attribute achievement)
CBAM extends ATAM with economic analysis (ROI-driven). Perform early when cost of change is minimal. Lightweight: Mini-ATAM (half-day workshop).
Cloud Resilience Patterns
Circuit Breaker
Monitor failures; after threshold fail fast ("open"); periodically test recovery. States: Closed, Open, Half-Open. Prevents cascading failures.
Retry with Exponential Backoff
1s, 2s, 4s, 8s + jitter. Only transient errors, not business logic. Operations must be idempotent.
Bulkhead
Isolate elements into pools; one failure doesn't affect others. Separate connection/thread pools per feature/tenant.
Throttling
Rate limiting, concurrency limiting, resource quotas per user/tenant/service.
Saga Pattern
Distributed transactions as local transaction sequence with compensating rollbacks. Choreography (decentralized) vs Orchestration (centralized).
API Architecture: REST vs GraphQL
REST: resource-based URLs, HTTP verbs, stateless, standard caching. Best for: public APIs, simple CRUD, caching-critical.
GraphQL: single endpoint, client-specified queries, typed schema. Best for: mobile (bandwidth), nested data, rapid frontend iteration.
Hybrid: GraphQL gateway aggregating REST/RPC backends.
Security for GraphQL: query depth limiting, complexity analysis, timeout, field-level auth.
ADR Templates
Nygard (most common): Title, Status (Proposed/Accepted/Deprecated/Superseded), Context, Decision, Consequences
MADR (extended): adds trade-off analysis, considered options with pros/cons
Y-Statement (concise): "In context of [use case], facing [concern], decided for [option] to achieve [quality], accepting [downside]"
Best practices: single decision per ADR | immutable (supersede, never modify) | store in VCS | create when decided
Technology Selection: Open Source Priority
Evaluation order: 1. Mature OSS with strong community | 2. Newer OSS with active dev | 3. Proprietary only when specified or no viable OSS
OSS criteria: last commit <6 months | regular releases | quick issue resolution | 10+ regular contributors | >1000 GitHub stars for critical components
License preference: MIT > Apache 2.0 > BSD > MPL 2.0 > LGPL (caution) > GPL (careful) > AGPL (extreme caution). Proprietary forbidden without explicit request.
Document per selection: name/version, license, GitHub URL/stats, maintenance assessment, alternatives considered.
Contract Testing for External Integrations
External integrations (web APIs, third-party services, webhooks, OAuth providers) are the highest-risk boundary in any system. Breaking changes in external APIs cause production failures that unit and integration tests cannot catch.
Consumer-driven contracts verify that the provider's API still satisfies the consumer's expectations. The consumer defines the contract; the provider verifies against it. Breaking changes are detected at build time, not in production.
When to Recommend
Annotate for contract testing when the design includes:
- Third-party REST/GraphQL APIs (payment, email, analytics, auth providers)
- Webhooks from external services (Stripe events, GitHub webhooks)
- OAuth/OIDC providers (token exchange, userinfo endpoints)
- Internal APIs consumed across team boundaries (same org, different team)
Tool Recommendations by Language
| Language | Tool | Notes |
|---|
| Polyglot (any) | Pact | Consumer-driven, widest language support, Pact Broker for contract sharing |
| JVM (Java/Kotlin) | Spring Cloud Contract | Groovy/YAML DSL, generates stubs for consumers, tight Spring integration |
| .NET | PactNet | Pact implementation for .NET, NuGet package |
| Python | pact-python | Pact implementation for Python, pytest integration |
| JavaScript/TS | Pact-JS | Pact implementation for Node.js, Jest/Vitest compatible |
Handoff Annotation Format
When external integrations are detected, include in the handoff to platform-architect:
External Integrations Requiring Contract Tests:
- [Service Name] ([API type]): [what the system consumes]
Recommended: consumer-driven contracts via [tool] in CI acceptance stage
This enables platform-architect to include contract test execution in the CI/CD pipeline design.
