/nw-architectural-styles-tradeoffs

name: nw-architectural-styles-tradeoffs
description: Architectural style selection decision matrices, trade-off analysis, structural enforcement rules, and combination patterns. Load when choosing or evaluating architecture styles.
user-invocable: false
disable-model-invocation: true

Architectural Styles: Selection and Trade-offs

Style Selection Decision Tree

Start here. Answer the dominant driver, follow to recommended style.

Is the domain complex with rich business rules?
  YES -> Do you need infrastructure independence and high testability?
    YES -> Hexagonal / Clean / Onion (functionally equivalent, different terminology)
    NO  -> Is the domain well-understood with clear module boundaries?
      YES -> Modular Monolith (single deployment, structured boundaries)
      NO  -> Layered Architecture (simple, well-known, fast to start)
  NO -> Is this a feature-heavy application with independent feature teams?
    YES -> Vertical Slice (per-feature organization, CQRS-friendly)
    NO  -> Do you need independent deployment and scaling per capability?
      YES -> Can the team handle distributed system operational complexity?
        YES -> Microservices
        NO  -> Modular Monolith (extract to services later)
      NO  -> Is the primary concern async workflows or event-driven processing?
        YES -> Event-Driven Architecture
        NO  -> Is this a data processing pipeline?
          YES -> Pipe and Filter
          NO  -> Layered Architecture (sensible default)

Cross-Cutting Comparison Matrix

| Style | Dep. Direction | Organization | Deployment | Best For | Team Size | |-------|---------------|-------------|------------|----------|-----------| | Hexagonal/Clean/Onion | Inward (DIP) | Ports + adapters | Single process | Infrastructure-agnostic domains | Any | | Layered (N-Tier) | Top-down | Horizontal layers | Single/multi-tier | Simple CRUD, rapid development | Small-medium | | Vertical Slice | Per-feature | Feature folders | Single process | Feature-heavy, CQRS systems | Medium-large | | Microservices | Per-service | Service boundaries | Distributed | Independent teams, polyglot | Large | | Event-Driven | Pub-sub | Events + handlers | Distributed | Async workflows, audit, decoupling | Medium-large | | CQRS | Read/write split | Command + query models | Single or distributed | Different read/write scaling | Medium | | Pipe and Filter | Data flow | Sequential filters | Single or distributed | ETL, data processing | Any | | Modular Monolith | Inward per module | Domain modules | Single process | Structured monolith, future extraction | Small-medium |

When-to-Use / When-NOT Decision Matrix

Hexagonal / Clean / Onion (equivalent patterns, different names)

| Use When | Avoid When | |----------|-----------| | Multiple client types consume same domain logic | Simple CRUD with single data store | | UI/DB technologies need periodic refresh | Latency-critical paths (added indirection) | | High testability required -- domain testable without infra | Small team where adapter overhead outweighs benefit | | Alignment with DDD desired | Application will never change infrastructure |

Vertical Slice

| Use When | Avoid When | |----------|-----------| | Teams understand code smells and refactoring patterns | Teams unfamiliar with refactoring -- slices diverge | | Feature-heavy apps where changes affect one feature | Heavy cross-cutting concerns (shared validation, auth) | | CQRS systems with independent commands/queries | Early projects with poorly understood domain | | Minimize cross-cutting changes on new features | Need strong architectural governance |

Microservices

| Use When | Avoid When | |----------|-----------| | Multiple teams need independent deployment cycles | Small teams (operational overhead per service) | | Different system parts need different tech stacks | Greenfield with unclear boundaries -- start modular monolith | | Independent scaling of capabilities adds value | Strong transactional consistency required across boundaries | | Organization supports operational complexity | Risk of "grains of sand" anti-pattern |

Modular Monolith

| Use When | Avoid When | |----------|-----------| | Greenfield with unclear domain boundaries | Independent deployment of components required | | Non-trivial complexity benefiting from module isolation | Different modules need different tech stacks | | Module autonomy without distributed overhead | Team ready for microservices operational complexity | | Microservice-like structure with monolith simplicity | -- |

Event-Driven / CQRS

| Use When | Avoid When | |----------|-----------| | Loose coupling between producers and consumers | Simple request-response applications | | Workflows spanning multiple services (eventual consistency) | Strong immediate consistency required | | Complete audit trails needed (event sourcing) | Team unfamiliar with eventual consistency | | Read/write workloads have very different scaling needs | Simple CRUD where two models add unjustified overhead |

Pipe and Filter

| Use When | Avoid When | |----------|-----------| | Processing decomposes into independent, reorderable steps | Request-response requiring synchronous completion | | Steps have different scalability requirements | Steps must execute as single transaction | | Flexibility to add/remove/reorder steps needed | Steps require significant shared state | | ETL, image processing, compiler pipelines | -- |

Combination Patterns

Styles are composable. The "Explicit Architecture" approach (Herberto Graca) combines:

| Pattern | Role in Combined Architecture | |---------|-------------------------------| | Hexagonal | Framework connecting external tools to the core | | Onion | Organizes layers within the hexagon | | DDD | Supplies domain concepts and bounded contexts | | Clean | Reinforces dependency inversion rules | | CQRS | Separates commands from queries within each bounded context |

Practical rule: