architecture-advisor

Architecture Advisor

Core Principles

1. Ask before recommending — Never prescribe an architecture without understanding the project. Run the questionnaire first to gather context about domain, team, lifetime, and constraints.
2. Right-size the architecture — The best architecture is the simplest one that handles the project's actual complexity. CRUD apps do not need DDD. Startups do not need Clean Architecture. Match complexity to real requirements, not aspirations.
3. Architecture is not permanent — Every architecture has an evolution path. Start simple and add structure when complexity demands it. Document the decision so the team knows when to evolve.
4. Four supported architectures — dotnet-claude-kit provides first-class patterns for Vertical Slice Architecture (VSA), Clean Architecture (CA), DDD + Clean Architecture, and Modular Monolith. Each has specific strengths and trade-offs.

The Architecture Questionnaire

Before recommending an architecture, ask questions across these 6 categories. Not every question applies to every project — skip irrelevant ones.

Category 1: Domain Complexity

Category 2: Team & Organization

Category 3: System Lifetime & Scale

Category 4: Regulatory & Compliance

Category 5: Existing Codebase

Category 6: Integration Complexity

Decision Matrix

Map questionnaire answers to architecture recommendations:

When Signals Conflict

If signals point to different architectures:

1. Default to simpler — When in doubt, start with VSA and evolve
2. Domain complexity wins — High domain complexity overrides team size and lifetime signals
3. Team familiarity matters — A team experienced with CA will be more productive with CA than learning VSA, even if VSA is technically simpler
4. Compliance drives structure — Regulatory requirements often force stricter boundaries (CA or DDD)

Patterns

Vertical Slice Architecture (VSA)

Organize by feature, not by layer. Each operation is a self-contained slice.

src/MyApp.Api/
  Features/
    Orders/CreateOrder.cs    # Request + Handler + Response + Endpoint
    Orders/GetOrder.cs
  Common/
    Behaviors/ValidationBehavior.cs
    Persistence/AppDbContext.cs

Best for: CRUD-heavy apps, APIs, MVPs, small-medium teams, short-medium lifetime. Load skill: vertical-slice

Clean Architecture (CA)

Concentric layers with dependency inversion. Domain at the center, infrastructure at the edge.

src/
  MyApp.Domain/              # Entities, interfaces, domain logic
  MyApp.Application/         # Use cases, DTOs, validation
  MyApp.Infrastructure/      # EF Core, external services
  MyApp.Api/                 # Endpoints, middleware

Best for: Medium complexity, long-lived systems, teams familiar with layered patterns. Load skill: clean-architecture

DDD + Clean Architecture

Clean Architecture with tactical DDD patterns: aggregates, value objects, domain events.

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:

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