dotnet-webapp-template

A production-grade layered .NET 10 template with clean architecture, full test coverage, and modern DevOps.

.NET	10.0
Database	PostgreSQL (EF Core)
API Style	Minimal APIs
UI	Blazor Server
Auth	JWT Bearer (API) + OIDC (UI) — optional
Observability	OpenTelemetry (traces + metrics)
CI	Forgejo Actions

Architecture

src/
├── CrossCutting/
│   └── DataClasses/                       # POCOs, DTOs, Result<T>
├── Logic/
│   ├── Domain/
│   │   ├── PlaceholderManagement/         # Domain logic (Managers)
│   │   └── PlaceholderManagement.Contract/
│   └── Business/
│       ├── PlaceholderWorkflows/          # Process orchestration
│       └── PlaceholderWorkflows.Contract/
├── Infrastructure/
│   └── DiMappings/                        # Centralized DI registration
├── Data/
│   ├── DataStoring/                       # EF Core DbContext + Repositories
│   └── DataStoring.Contract/
└── UI/
    ├── ServiceClient/                     # Minimal API (backend)
    └── WebClient/                         # Blazor Server (frontend)

Layer	Purpose
DataClasses	POCOs, DTOs — no logic, no dependencies
Domain (Contract + Impl)	Business logic, domain state (Managers)
Business (Contract + Impl)	Process orchestration (Workflows)
Infrastructure	DI wiring, cross-cutting concerns
Data (Contract + Impl)	EF Core persistence (Repositories)
UI — ServiceClient	Minimal API with health checks, versioning, OpenTelemetry
UI — WebClient	Blazor Server with OIDC auth

Key Patterns

• Result<T> — all domain operations return success/failure (no exceptions for control flow)
• Contracts/Implementation separation — every layer depends on abstractions
• Repository pattern with explicit SaveChangesAsync (Unit of Work)
• FluentValidation — request validation via validators
• Global exception handling — structured error responses via IExceptionHandler

Prerequisites

• .NET 10.0 SDK
• PostgreSQL (via docker compose up -d or local install)
• Node.js 22+ (for WebClient Tailwind CSS)

Quick Start

# 1. Clone and restore
git clone <repo-url> && cd dotnet-webapp-template
dotnet restore

# 2. Set up environment
cp .env.example .env    # edit as needed

# 3. Start infrastructure
docker compose up -d

# 4. Build and test
dotnet build
dotnet test

# 5. Run
dotnet run --project src/UI/ServiceClient
dotnet run --project src/UI/WebClient

# Or via Docker:
docker compose up

Development

Tests

dotnet test                         # build + run all tests
dotnet test tests/PlaceholderManagement.Tests/
dotnet test tests/PlaceholderWorkflows.Tests/
dotnet test tests/ServiceClient.Tests/

WebClient Tailwind CSS

cd src/UI/WebClient
npm ci
npm run build:css        # manual build
# Or let MSBuild do it automatically during dotnet build

Configuration

All configuration is in appsettings.json / environment variables. See .env.example for all options.

API Endpoints (ServiceClient)

Method	Path	Description
GET	/health/live	Liveness check
GET	/health/ready	Readiness check (DB)
GET	/api/placeholder-items	List all items
POST	/api/placeholder-items	Create item
GET	/api/placeholder-items/{id}	Get by ID
PUT	/api/placeholder-items/{id}	Update item
DELETE	/api/placeholder-items/{id}	Delete item

API versioning via ApiVersion query parameter (default: 1.0).

Renaming the Template

# Replace in all files:
#   RepoOwner     → your org/user
#   ProjectName   → your project name
#   Placeholder*  → your domain concepts
#   ProjectName.sln → your solution name

Documentation

File	Content
docs/dotnet-coding-guide.md	Coding conventions, Pattern Catalogue, architecture rules
docs/auth.md	JWT + OIDC setup guides (Auth0, Azure AD, Keycloak)
docs/architecture.md	Detailed architecture overview
AGENTS.md	AI agent reference (opencode / cursor)

CI/CD (Forgejo Actions)

• build.yaml — Restore → npm ci → Build → Test (+ coverage) → Publish → Docker
• ai-review.yaml — Automatic AI code review on PRs (OpenAI-compatible API)

License

Apache License 2.0