| 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
Gate design invariants — WHAT/WHY/HOW and GDP-1..9 (moved)
These two STANDING contracts are paradigm- and role-independent, so they live in ONE shipped
home instead of being restated per role: nw-cross-cutting-invariants (clause ids
gate:self-explaining-what-why-how, gate:design-principles-gdp-1-9). Load that skill when
designing any gate, oracle, or error surface; cite the clause id, never re-declare the text.
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.
Delivery boundary projection
Keep component boundaries, unbounded input/state domains, typed failures and
port invariants in the durable architecture brief. For one delivery, project
only the applicable facts into the existing DeliveryContract.targets
boundary, contract shape and closed obligations. This preserves the design
facts without a second per-feature manifest or validation gate.
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.
