dotnet-architecture

.NET Architecture Standards

.NET-specific structural standards. For universal architecture principles, see engineering-architecture.mdc.

Conflict resolution: Where this file provides .NET-specific guidance that differs from engineering-architecture.mdc, this file takes precedence for .cs, .csproj, .sln, .bicep, .tf, .yaml, and .yml files. The universal rule provides the default; this rule provides the override.

---

Clean Architecture in .NET

Dependency direction: outer layers depend on inner layers; inner layers have no knowledge of outer layers.

Presentation (Api)  →  Application  →  Domain
Infrastructure                      →  Domain
Infrastructure                      →  Application (interfaces)

Domain — entities, value objects, domain events, domain exceptions. No framework dependencies.

Application — commands, queries (CQRS), handlers, validators, application exceptions, IRepository interfaces. No infrastructure imports.

Infrastructure — EF Core, message brokers, HTTP clients, external service adapters, DI registration.

Presentation (Api) — controllers, Minimal API endpoints, middleware, global error handler, request/response mapping.

---

CQRS and MediatR

• Commands: change state, enforce domain rules, return Result<T> or void
• Queries: read-only, project to consumer DTOs, use AsNoTracking()
• Register pipeline behaviours: ValidationBehavior, LoggingBehavior, TransactionBehavior
• Never return domain entities from handlers; return identifiers or DTOs

// Command
public record PlaceOrderCommand(Guid CustomerId, IReadOnlyList<OrderLineDto> Lines)
    : IRequest<Result<Guid>>;

// Query
public record GetOrderByIdQuery(Guid OrderId) : IRequest<OrderDetailDto?>;

---

Feature-first organisation

Organise by feature, not by technical role:

Application/
├── Orders/
│   ├── Commands/PlaceOrder/
│   │   ├── PlaceOrderCommand.cs
│   │   ├── PlaceOrderCommandHandler.cs
│   │   └── PlaceOrderCommandValidator.cs
│   └── Queries/GetOrderById/
│       ├── GetOrderByIdQuery.cs
│       ├── GetOrderByIdQueryHandler.cs
│       └── OrderDetailDto.cs
└── Common/
    ├── Behaviours/
    └── Exceptions/