nw-architectural-styles-tradeoffs

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: hexagonal/clean/onion are the SAME pattern with different terminology. All enforce DIP with inward dependency flow. Pick one vocabulary and use it consistently.

Enforceable Structural Rules

Architecture rules are only real if they are enforced. Key rules by style:

Hexagonal

| Rule | Enforcement |

|------|-------------|

| Domain has zero imports from adapters/infra | import-linter (Python), ArchUnit (Java), ArchUnitTS (TS) |

| All external communication via port interfaces | Code review + architecture tests |

| No adapter-to-adapter dependencies | Package dependency check |

| All dependencies point inward toward domain | Layer dependency rule |

Modular Monolith

| Rule | Enforcement |

|------|-------------|

| No cross-module database access | Schema ownership tests |

| Interface-only communication between modules | Module independence contract |

| No circular dependencies between modules | Cycle detection |

| Module internals inaccessible from outside | Package/import visibility rules |

Vertical Slice

| Rule | Enforcement |

|------|-------------|

| Slices must not import from other slices | Independence contract |

| All code for a feature resides within its slice | Containment check |

| Cross-slice communication via events/contracts only | Import rules |

Architecture Enforcement Tooling

| Language | Tool | Approach |

|----------|------|----------|

| Java/Kotlin | ArchUnit | Fluent API unit tests, predefined architecture rules |

| TypeScript/JS | ArchUnitTS | File-based dependency rules, Jest/Vitest integration |

| TypeScript/JS | dependency-cruiser | Comprehensive dependency analysis, JSON/dot/HTML reports, .dependency-cruiser.js config, widely adopted |

| Python | import-linter | Config-based contracts (forbidden, layers, independence) |

| Python | PyTestArch | pytest-based architecture tests |

| Python | pytest-archon | pytest-native architecture tests, modern alternative to import-linter, decorator-based rules |

| .NET | NetArchTest | NUnit/xUnit architecture rules |

| Go | go-arch-lint | YAML-based dependency rules |

Python Example (import-linter)

[importlinter:contract:hexagonal-domain]
name = Domain must not import from infrastructure
type = forbidden
source_modules = myapp.domain
forbidden_modules = myapp.infrastructure, myapp.adapters

[importlinter:contract:module-independence]
name = Feature modules must be independent
type = independence
modules =
    myapp.modules.orders
    myapp.modules.billing
    myapp.modules.shipping

Run lint-imports in CI as first-stage fast check (analyzes imports, no I/O).

Common Anti-Patterns

| Anti-Pattern | Style | Signal | Fix |

|-------------|-------|--------|-----|

| Shared database | Microservices | Services query each other's tables | Database per service; API contracts |

| Distributed monolith | Microservices | Services deploy together | Re-evaluate boundaries; consider modular monolith |

| Grains of sand | Microservices | Too-fine-grained services, constant coordination | Merge into coarser services aligned to bounded contexts |

| Anemic domain model | Layered | Entities are data bags, logic in services | Move behavior into entities/value objects |

| Big ball of mud | Modular Monolith | Module boundaries violated, cross-imports | Add architecture tests, enforce with CI |

| Pass-through layers | Clean | Layers that add no value, just forward calls | Remove unnecessary layers; keep only those adding behavior |

Annotating for Software Crafter

When the architecture document specifies an architectural style, include an enforcement annotation so the software-crafter knows which tooling to set up during DELIVER.

What to Include in the Design Document

1. Style chosen and the key structural rules that apply (from the Enforceable Structural Rules section above)
2. Recommended enforcement tool appropriate for the project's language (from the Architecture Enforcement Tooling table)
3. Specific rules to enforce expressed as constraints the tool can verify

Annotation Format

## Architecture Enforcement

Style: [Hexagonal | Modular Monolith | Vertical Slice | ...]
Language: [Python | Java | TypeScript | ...]
Tool: [tool name from table above]

Rules to enforce:
- [Rule 1 from Enforceable Structural Rules, e.g., "Domain has zero imports from adapters/infra"]
- [Rule 2, e.g., "No cross-module database access"]

This annotation flows through acceptance-designer to software-crafter, who implements the architecture tests during the GREEN phase alongside the first component that establishes the structural boundary.