POS — .NET 8 Clean Architecture Template

A reusable .NET 8 Clean Architecture solution intended as a starting point for new services across the organization. Project folders are named with the project prefix (POS.*) and live at the repository root — there is no src/ folder.

Project layout

.
├── POS.Domain/                          # Enterprise rules: entities, value objects, domain events, exceptions
├── POS.Application/                     # Use cases (CQRS via MediatR), validators, behaviors, interfaces
├── POS.Infrastructure/                  # EF Core DbContext, persistence, external services, interceptors
├── POS.WebApi/                          # ASP.NET Core entry point: controllers, middleware, Swagger, Serilog
├── POS.Domain.UnitTests/
├── POS.Application.UnitTests/
├── POS.Infrastructure.IntegrationTests/
├── POS.WebApi.FunctionalTests/
├── POS.sln
├── Directory.Build.props                # Shared MSBuild props (TFM, nullable, warnings-as-errors)
├── Directory.Packages.props             # Central NuGet package version management
├── global.json                          # Pinned .NET SDK version
├── Dockerfile
├── docker-compose.yml
└── .github/workflows/                   # CI + CodeQL

Dependency rule (inward only)

WebApi  ─►  Application  ─►  Domain
   │            ▲
   ▼            │
Infrastructure ─┘

• Domain depends on nothing.
• Application depends only on Domain.
• Infrastructure depends on Application and Domain.
• WebApi depends on Application and Infrastructure (composition root).

Reusing this template for a new project

This is the canonical template — when starting a new service, copy this repository and rename POS to your project's prefix (for example Inventory, Billing):

1. Create a new repo from this template (or copy the contents).
2. Rename folders, project files, namespaces, and the solution from POS to <YourProject> (for example using a tool like dotnet-rename or your editor's solution-wide rename).
3. Update appsettings.json and docker-compose.yml connection strings.
4. Replace the sample Product vertical slice with your real aggregates.

Running locally

# Restore and build
dotnet build POS.sln

# Run the API (uses an in-memory database when no connection string is configured)
dotnet run --project POS.WebApi

# Open Swagger
# https://localhost:5001/swagger

Running with Docker

docker compose up --build
# API:    http://localhost:8080
# Health: http://localhost:8080/health

Tests

dotnet test POS.sln

• POS.Domain.UnitTests — pure unit tests for entities, value objects, events.
• POS.Application.UnitTests — use-case and validator tests (NSubstitute for fakes).
• POS.Infrastructure.IntegrationTests — EF Core / persistence tests.
• POS.WebApi.FunctionalTests — end-to-end HTTP tests via WebApplicationFactory.

Adding a new feature (vertical slice)

Use the included Product feature as a reference. For each new aggregate:

1. Domain — add an entity in POS.Domain/Entities (inherit BaseAuditableEntity for auditing, raise BaseEvents for domain events).
2. Application — under POS.Application/<Feature>/:
   • Commands/<Verb><Feature>/ — Command record, Validator, Handler.
   • Queries/<Verb><Feature>/ — Query record, Validator (if needed), Handler.
   • DTO classes for read models.
3. Infrastructure — add an EF Core configuration in POS.Infrastructure/Persistence/Configurations/, expose a DbSet on IApplicationDbContext and ApplicationDbContext, then add a migration.
4. WebApi — add a controller under POS.WebApi/Controllers/.
5. Tests — add unit tests for the validator/handler and a functional test for the endpoint.

Cross-cutting concerns

• MediatR pipeline behaviors (registered in POS.Application/DependencyInjection.cs): UnhandledExceptionBehavior, ValidationBehavior, LoggingBehavior, PerformanceBehavior.
• Auditing & domain events — handled by EF Core SaveChanges interceptors in POS.Infrastructure/Persistence/Interceptors/.
• Global error handling — ExceptionHandlingMiddleware returns RFC 7807 ProblemDetails responses.
• Logging — Serilog with console sink and request logging.
• Health checks — /health endpoint.
• OpenAPI — Swagger UI in Development.

Conventions

• TreatWarningsAsErrors=true is enforced solution-wide via Directory.Build.props.
• Nullable reference types and implicit usings are enabled everywhere.
• NuGet versions are managed centrally in Directory.Packages.props — do not put Version="..." on <PackageReference> items in csproj files.
• Test projects are auto-detected by name (*Tests) in Directory.Build.props.