PowerCSharp.CleanArchitecture.Template 1.0.0

PowerCSharp.CleanArchitecture

Clean Architecture .NET 8 WebApi starter template powered by PowerCSharp —
start your next project on a production-ready foundation, not from scratch.

What is this?

PowerCSharp.CleanArchitecture is a production-ready starter template for building ASP.NET Core Web APIs following Clean Architecture principles. It is opinionated by design: the architectural decisions, folder conventions, dependency rules, and cross-cutting concerns are already solved so you can focus on shipping your domain logic.

This repo is:

• A GitHub Template Repository — click "Use this template" to generate your own repo pre-populated with the full structure.
• A dotnet new template — scaffold locally with a single command (see Using as a Template).

Architecture Overview

The solution follows a strict dependency rule: inner layers never reference outer layers. Dependencies always point inward.

┌──────────────────────────────────────────────┐
│                   WebApi                     │  Composition root · host · middleware pipeline
├──────────────────────────────────────────────┤
│                 Presentation                 │  Controllers · HTTP response mapping · ApiResponse<T>
├─────────────────────────┬────────────────────┤
│       Application       │    Operational     │  CQRS · MediatR · validators   │   Resilience · Polly
├─────────────────────────┴────────────────────┤
│               Infrastructure                 │  Adapters · external services · DI wiring
├──────────────────────┬───────────────────────┤
│        Domain        │        Shared         │  Entities · interfaces · aggregates   │   Enums · constants
└──────────────────────┴───────────────────────┘

Project Structure

PowerCSharp.CleanArchitecture/
├── src/
│   ├── CleanArchitecture.Domain/           # Entities, aggregate root marker
│   ├── CleanArchitecture.Shared/           # Cross-layer enums & constants
│   ├── CleanArchitecture.Application/      # CQRS handlers, validators, behaviors
│   │   ├── Abstractions/                   # Ports (e.g. IDateTimeProvider)
│   │   ├── Api/
│   │   │   ├── Samples/                    # Living-doc sample use cases
│   │   │   └── Shared/                     # Shared application data/factories
│   │   └── Common/
│   │       ├── Behaviors/                  # MediatR pipeline behaviors
│   │       └── Handlers/                   # Shared handler utilities
│   ├── CleanArchitecture.Operational/      # Resilience (Polly retry pipelines)
│   ├── CleanArchitecture.Infrastructure/   # Adapters (DateTimeProvider, etc.)
│   ├── CleanArchitecture.Presentation/     # Controllers, ApiResponse<T> envelope
│   │   ├── Api/                            # Response types, attributes
│   │   ├── Controllers/
│   │   │   └── v1/                         # Versioned controllers (SamplesController)
│   │   └── Extensions/                     # Result → IActionResult mapping
│   └── CleanArchitecture.WebApi/           # Host: Program.cs, appsettings, Features
│       └── Features/                       # Host-local feature modules
├── tests/
│   ├── CleanArchitecture.Tests.Shared/     # Shared test utilities & fixtures
│   ├── CleanArchitecture.WebApi.UnitTests/ # Unit tests
│   └── CleanArchitecture.WebApi.IntegrationTests/ # Integration tests (WebApplicationFactory)
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                          # Build + test on push / PR
│   │   └── release.yml                     # Tag-triggered release & NuGet publish
│   ├── ISSUE_TEMPLATE/
│   └── pull_request_template.md
├── .template.config/
│   └── template.json                       # dotnet new template definition
├── Directory.Build.props                   # Shared build settings (TargetFramework, Nullable, etc.)
├── NuGet.Config                            # Package sources (nuget.org only)
├── global.json                             # Pinned .NET SDK version
├── Dockerfile                              # Multi-stage production image
├── docker-compose.yml                      # Local development stack
└── PowerCSharp.CleanArchitecture.sln

What's Included

Clean Architecture

• Strict dependency rule enforced by project references — outer layers cannot leak into inner layers.
• BaseEntity<TId> — generic, strongly-typed entity base in the Domain layer.
• IAggregateRoot — marker interface for aggregate roots.

CQRS via MediatR

• Commands and Queries separated into dedicated folders.
• BaseApiController.SendAsync<T>() dispatches through MediatR and maps the result to HTTP.
• LoggingBehavior<TRequest, TResponse> — MediatR pipeline behavior that logs every request/response automatically.

Validation via FluentValidation

• Validators registered automatically via assembly scanning.
• Integrated with MediatR pipeline — invalid requests are rejected before reaching handlers.

Consistent HTTP Responses

• ApiResponse<T> / ApiResponse envelope on every endpoint.
• Ardalis.Result used in handlers; extension method maps it to the correct HTTP status code automatically.

PowerCSharp Features Framework

Pluggable feature modules with flag-gating (PowerFeatures:<Key>:Enabled in appsettings.json):

Resilience

• Polly retry policies via IRetryPolicyProvider in the Operational layer — ready to wire into any infrastructure adapter.

Health Checks

• /health endpoint registered and mapped out of the box.

Living-Documentation Samples

The Samples feature (disabled by default, enabled in Development) ships working endpoint examples for:

• GET /v1/samples/cache — cache miss → hit demonstration
• GET /v1/samples/cache/status — inspect cache keys
• DELETE /v1/samples/cache — clear cache
• GET /v1/samples/disk-cache — disk cache demonstration
• Full integration tests covering the above

Prerequisites

Quick Start

Clone and run

git clone https://github.com/marioarce/PowerCSharp.CleanArchitecture.git
cd PowerCSharp.CleanArchitecture

dotnet restore
dotnet build
dotnet run --project src/CleanArchitecture.WebApi

The API starts on https://localhost:7xxx / http://localhost:5xxx. Open the Swagger UI at /swagger.

Run with Docker

docker compose up --build

The API is available at http://localhost:8080.

Using as a Template

Option A — GitHub Template (recommended for new repos)

1. Click "Use this template" at the top of this page.
2. Name your new repository and choose visibility.
3. GitHub creates a new repo with the full project structure — no fork, clean history.

Option B — dotnet new (scaffold locally)

# Install the template once
dotnet new install PowerCSharp.CleanArchitecture.Template

# Scaffold a new project
dotnet new powercsharp-cleanarchitecture --name MyAwesomeApi --output ./MyAwesomeApi
cd MyAwesomeApi
dotnet run --project src/MyAwesomeApi.WebApi

--name replaces CleanArchitecture everywhere: filenames, namespaces, project references, and the solution file.

Running Tests

# All tests
dotnet test

# Unit tests only
dotnet test tests/CleanArchitecture.WebApi.UnitTests

# Integration tests only
dotnet test tests/CleanArchitecture.WebApi.IntegrationTests

Integration tests use WebApplicationFactory<Program> — no external dependencies required.

Configuration

Key feature flags in appsettings.json:

{
  "PowerFeatures": {
    "Cors": { "Enabled": true, "AllowedOrigins": [ "https://localhost" ] },
    "Cache": { "Enabled": true, "Provider": "BitFaster", "Capacity": 1000 },
    "DiskCache": { "Enabled": true, "DirectoryPath": "./cache" },
    "Samples": { "Enabled": false }
  }
}

appsettings.Development.json overrides Samples.Enabled to true so the living-documentation endpoints are visible locally but hidden in production.

PowerCSharp Ecosystem

All packages are available on nuget.org:

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

License

This project is licensed under the MIT License.
Copyright (c) 2026 Mario Alberto Arce.