src/ MyApp.Domain/ # Aggregates, value objects, domain events, domain services MyApp.Application/ # Use cases orchestrating aggregates MyApp.Infrastructure/ # Persistence, external service adapters MyApp.Api/ # Thin endpoints

**Best for:** Complex domains, specialized vocabulary, strict invariants, experienced teams.
**Load skill:** `ddd` + `clean-architecture`

### Modular Monolith

Independent modules in a single deployable unit, each with its own architecture internally.

src/ MyApp.Host/ # Wires modules together Modules/ Orders/ # Own features, own DbContext, own architecture Catalog/ # Can use VSA, CA, or DDD internally MyApp.Shared/ # Integration event contracts only

**Best for:** Multiple bounded contexts, team-per-domain, future microservices extraction.
**Load template:** `modular-monolith`

## Evolution Paths

Architecture is not a one-time decision. Systems evolve. Here are the common migration paths:

| From | To | Trigger | How |
|------|----|---------|-----|
| VSA | CA | Domain logic growing beyond handlers | Extract Domain + Application layers, keep features as use cases |
| VSA | Modular Monolith | Multiple bounded contexts emerging | Group features into modules, add module boundaries |
| CA | DDD + CA | Invariants becoming complex, primitive obsession | Introduce aggregates, value objects, domain events |
| Monolith | Modular Monolith | Teams stepping on each other, shared database coupling | Split into modules with own DbContexts and schemas |
| Modular Monolith | Microservices | Independent scaling needs, independent deployment | Extract modules into separate deployable services |

## Anti-patterns

### Picking Clean Architecture for a CRUD App

// BAD — 4 projects, 6+ files per feature for simple CRUD src/MyApp.Domain/Entities/Product.cs src/MyApp.Application/Products/CreateProduct/CreateProductCommand.cs src/MyApp.Application/Products/CreateProduct/CreateProductHandler.cs src/MyApp.Application/Products/CreateProduct/CreateProductValidator.cs src/MyApp.Infrastructure/Persistence/ProductRepository.cs src/MyApp.Api/Endpoints/ProductEndpoints.cs

// GOOD — VSA: 1 file for a simple CRUD feature src/MyApp.Api/Features/Products/CreateProduct.cs

### DDD Everywhere

// BAD — value objects and aggregates for a settings table public class UserSettings : AggregateRoot // overkill { public ThemeName Theme { get; private set; } // value object for "dark"/"light"? public void ChangeTheme(ThemeName theme) { /* domain event? really? */ } }

// GOOD — simple entity for simple data public class UserSettings { public Guid UserId { get; init; } public string Theme { get; set; } = "light"; }

### Premature Microservices

// BAD — splitting into 5 microservices on day one with 2 developers OrderService (own repo, own DB, own CI/CD) CatalogService (own repo, own DB, own CI/CD) IdentityService (own repo, own DB, own CI/CD) NotificationService (own repo, own DB, own CI/CD) GatewayService (own repo, own CI/CD)

// GOOD — start as a modular monolith, extract when you have evidence src/ Modules/Orders/ Modules/Catalog/ Modules/Identity/ Modules/Notifications/

### Skipping the Questionnaire

// BAD — "I always use Clean Architecture" User: "Set up a new project for a todo app" Agent: immediately scaffolds 4-project CA solution

// GOOD — ask first, then recommend User: "Set up a new project for a todo app" Agent: "Let me ask a few questions about your project to recommend the best architecture..." Agent: runs questionnaire, recommends VSA for low-complexity app

## Decision Guide

| Scenario | Recommendation |
|----------|---------------|
| New project, unknown requirements | Run the questionnaire |
| Simple CRUD API, 1-3 developers | VSA |
| Medium complexity, long-lived, experienced team | Clean Architecture |
| Complex domain, specialized vocabulary | DDD + Clean Architecture |
| Multiple bounded contexts, multiple teams | Modular Monolith |
| Existing N-tier codebase, needs modernization | Clean Architecture (familiar migration) |
| MVP / startup, speed is priority | VSA |
| Regulatory / compliance-heavy | Clean Architecture or DDD (enforced boundaries) |
| Will need independent scaling later | Modular Monolith (extraction-ready) |