When NOT to Use Clean Architecture — Trade-offs, Complexity, and Alternatives

Costs:
  ✗ Boilerplate: every use case needs a command/query record, handler, validator,
    repository interface update, and potentially a response DTO
  ✗ Navigation overhead: following a feature from controller → handler → domain
    → repository → DB is 4 hops in 4 different projects
  ✗ Onboarding time: new developers need to understand all 4 layers, the Result
    pattern, domain events, and the CQRS split before contributing
  ✗ Indirection: handlers are the right abstraction until they are not — sometimes
    a simple function is faster and clearer

Benefits (when they apply):
  ✓ Testable business logic without infrastructure
  ✓ Swappable infrastructure (DB, email, cache) without touching business logic
  ✓ Navigable architecture — clear "where does this go" decisions
  ✓ Long-term maintainability as complexity grows
  ✓ Multiple team members can work on different layers without conflicts

// For a small API with 10 endpoints, this is enough:
app.MapPost("/patients", async (CreatePatientDto dto, AppDbContext db) =>
{
    var patient = new Patient { Name = dto.Name, MRN = dto.MRN };
    db.Patients.Add(patient);
    await db.SaveChangesAsync();
    return Results.Created($"/patients/{patient.Id}", patient);
});

// Adding layers, handlers, interfaces, and repositories for 10 endpoints
// is not architecture — it is overhead

If every "feature" is:
  - Get record by ID
  - List records with filtering
  - Create record (validate + insert)
  - Update record (validate + upsert)
  - Delete record

Then Clean Architecture adds layers that have no business logic to contain.
Use Minimal APIs + EF Core + FluentValidation directly.

When the requirement is "build a prototype by Friday and we'll see if users like it":
  Clean Architecture adds 2-3x the setup time
  The prototype may be thrown away — all the infrastructure work is wasted

Start simple. If the prototype survives, migrate toward Clean Architecture
incrementally as the application grows.

The collaboration benefits of Clean Architecture (clear layer ownership, parallel
development, explicit interfaces between teams) do not apply when one developer
owns everything. The overhead is all cost, no benefit.

Organize by feature, not by layer:
  Features/
    Patients/
      CreatePatient/
        CreatePatientEndpoint.cs    ← HTTP handling
        CreatePatientHandler.cs     ← business logic
        CreatePatientValidator.cs   ← validation
        CreatePatientDb.cs          ← DB query
    Prescriptions/
      AddPrescription/
        ...

Best for:
  ✓ Teams where each feature is owned end-to-end by one developer
  ✓ Applications where features are largely independent
  ✓ When you want to colocate all related code in one place

Drawback:
  ✗ Cross-feature shared code can become unclear — "where does the shared patient
    validation go?"
  ✗ Architecture rules are harder to enforce with NetArchTest

// Best for: microservices with 3-5 endpoints, serverless functions
app.MapPost("/prescriptions", async (
    AddPrescriptionDto dto,
    AppDbContext db,
    IValidator<AddPrescriptionDto> validator) =>
{
    var validation = await validator.ValidateAsync(dto);
    if (!validation.IsValid)
        return Results.ValidationProblem(validation.ToDictionary());

    var patient = await db.Patients.FindAsync(dto.PatientId);
    if (patient is null)
        return Results.NotFound();

    // ... add prescription
    return Results.Ok(new { prescriptionId });
});

A middle ground: separate modules (Patients, Pharmacy, Billing), each with
its own Clean Architecture internally, but all in one deployable unit.

Best for:
  ✓ Large applications that are not ready for microservices
  ✓ When you want module isolation without deployment complexity
  ✓ As a stepping stone toward microservices

Each module has its own DbContext, its own domain, its own application layer.
Modules communicate through events or a shared kernel, not direct calls.

Questions to ask before choosing Clean Architecture:

1. Will this application grow beyond 20 features?
   YES → Clean Architecture
   NO  → Minimal API or Vertical Slice

2. Are there genuine domain rules that change independently of infrastructure?
   YES → Clean Architecture (the domain layer earns its keep)
   NO  → Simpler approach

3. Will multiple developers work on this simultaneously?
   YES → Clean Architecture (clear layer ownership prevents conflicts)
   ONE DEVELOPER → Simpler approach

4. Do you need to swap infrastructure (DB, email provider)?
   YES → Clean Architecture (interfaces make this safe)
   NO  → Probably not worth the overhead

5. Will this application live for more than 2 years?
   YES → Clean Architecture (the upfront cost pays back over time)
   NO  → Simpler approach

Phase 1: Extract business logic from controllers → put in service classes
Phase 2: Define interfaces for services → make infrastructure swappable
Phase 3: Separate Domain from Application → domain has no external dependencies
Phase 4: Add architecture tests → enforce the new structure
Phase 5: Add CQRS → separate command and query handlers