/nw-architecture-patterns

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: 1. **System Context**: system + users + external systems (stakeholder view) 2. **Containers**: applications, data stores, deployment units (technical overview) 3. **Components**: internal modules within containers (developer view) 4. **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: 1. **Functional Suitability**: completeness, correctness, appropriateness 2. **Performance Efficiency**: time behavior, resource utilization, capacity 3. **Compatibility**: coexistence, interoperability 4. **Usability**: learnability, operability, accessibility 5. **Reliability**: maturity, availability, fault tolerance, recoverability 6. **Security**: confidentiality, integrity, non-repudiation, accountability, authenticity 7. **Maintainability**: modularity, reusability, analyzability, modifiability, testability 8. **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