nwave-ai/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 [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.