> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/solution-and-architecture-standards/modular-clean-architecture.md).

# Modular Clean Architecture

## Purpose

AIC uses modular clean architecture to keep business rules independent of delivery mechanisms.

This protects the system from framework churn, improves testability, supports reuse and reduces the risk of business logic being trapped in UI, API or data access code.

## Standard Layers

### Domain

Contains:

* entities
* value objects
* domain services
* domain events
* domain exceptions
* business invariants

Does not contain:

* EF Core attributes unless explicitly accepted
* HTTP concepts
* JSON concerns
* WPF or MAUI types
* database transaction logic
* external service clients

### Application

Contains:

* use cases
* commands
* queries
* handlers
* validators
* interfaces for infrastructure
* transaction orchestration
* authorization checks close to use cases where appropriate

### Infrastructure

Contains:

* EF Core DbContext
* repositories where used
* external API clients
* file storage
* message bus adapters
* email and notification adapters
* identity provider integration
* configuration-bound implementation classes

### Presentation / Transport

Contains:

* ASP.NET Core endpoints or controllers
* WPF views and ViewModels
* MAUI pages and ViewModels
* request/response mapping
* UI-specific validation messages

## Dependency Rules

* Domain must be framework-light.
* Application can depend on Domain.
* Infrastructure can depend on Application and Domain.
* API/UI can depend on Application.
* API/UI should not depend directly on Infrastructure except for composition root wiring.

## Composition Root

Dependency injection registration belongs at the application boundary:

```csharp
builder.Services.AddApplication();
builder.Services.AddInfrastructure(builder.Configuration);
builder.Services.AddApiDefaults();
```

Each layer may expose extension methods, but they must not hide surprising behaviour.

## Common Mistakes

Avoid:

* entities that know about DbContext
* controllers that execute SQL
* ViewModels that contain complex business workflows
* infrastructure classes leaking through application interfaces
* generic repository abstractions that add no value
* domain models shaped only by database tables
* abstractions for abstractions' sake

## Architecture Fitness Checks

Use tests or analysis to check:

* Domain has no forbidden references
* Application has no UI references
* API endpoints do not depend directly on DbContext unless explicitly approved
* Infrastructure is the only layer containing external service clients