Nw Architectural Styles TradeoffsSAFE

AI agents that guide you from idea to working code, with you in control at every step.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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:

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.