nw-architecture-patterns

# 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 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 [quali