clean-architecture

What this skill does

# .NET Clean Architecture Skill

This skill helps you build, migrate, and maintain .NET monolithic applications following Clean Architecture principles and Domain-Driven Design patterns, based on Microsoft's eShopOnWeb reference application.

## Commands

### `/clean-arch:new`
**Interactive project scaffolding wizard**
Scaffold a new Clean Architecture solution from scratch with your choice of API style, database, and testing setup.

### `/clean-arch:migrate`
**Brownfield migration assistant**
Analyze and migrate existing codebases to Clean Architecture, guiding you through layer separation and refactoring.

### `/clean-arch:add-feature <EntityName>`
**Feature generator**
Generate a complete CRUD feature across all layers: entity, repository, specifications, service, API endpoints, and tests.

### `/clean-arch:audit`
**Architecture validator**
Scan your project for architecture violations, dependency issues, and anti-patterns with actionable fix suggestions.

### `/clean-arch:patterns`
**Pattern library browser**
Browse and copy proven Clean Architecture patterns: Repository, Specification, Domain Events, DI, Testing, and more.

## Prerequisites

- .NET 10 SDK or later
- Basic understanding of C#, ASP.NET Core, and Entity Framework Core
- Familiarity with SOLID principles

---

# Section A: Clean Architecture Overview

## What is Clean Architecture?

Clean Architecture is an architectural pattern that separates concerns into distinct layers with clear dependency rules:

```
┌─────────────────────────────────────────┐
│         Presentation (API/Web)          │  ← User Interface
│  Controllers/Endpoints, Pages, ViewModels│
└────────────┬────────────────────────────┘
             │ depends on ↓
┌────────────▼────────────────────────────┐
│        Application Core (Domain)         │  ← Business Logic
│  Entities, Interfaces, Services,        │
│  Specifications, Domain Events           │
└────────────┬────────────────────────────┘
             │ depends on ↓
┌────────────▼────────────────────────────┐
│         Infrastructure (Data)            │  ← External Concerns
│  DbContext, Repositories, Identity,     │
│  Email, File System, External APIs      │
└──────────────────────────────────────────┘
```

**Key Principle:** Dependencies point INWARD. The Application Core has NO dependencies on external layers.

## Project Structure

```
MySolution/
├── src/
│   ├── ApplicationCore/              # Domain layer (no dependencies)
│   │   ├── Entities/                 # Domain entities & aggregates
│   │   ├── Interfaces/               # Service & repository contracts
│   │   ├── Services/                 # Business logic
│   │   ├── Specifications/           # Query objects
│   │   ├── Events/                   # Domain events
│   │   └── Exceptions/               # Domain exceptions
│   │
│   ├── Infrastructure/               # Data access & external concerns
│   │   ├── Data/                     # EF Core DbContext, migrations
│   │   │   ├── Config/               # Entity configurations
│   │   │   └── Migrations/           # EF migrations
│   │   ├── Identity/                 # ASP.NET Identity
│   │   └── Services/                 # Infrastructure services (email, etc.)
│   │
│   └── API/                          # Presentation layer (FastEndpoints)
│       ├── Endpoints/                # API endpoints
│       │   ├── ProductEndpoints/
│       │   ├── OrderEndpoints/
│       │   └── AuthEndpoints/
│       ├── Extensions/               # DI registration
│       └── Program.cs                # Application startup
│
└── tests/
    ├── UnitTests/                    # Fast, isolated tests
    │   ├── ApplicationCore/
    │   └── Builders/                 # Test data builders
    ├── IntegrationTests/             # Repository + DB tests
    └── FunctionalTests/              # API end-to-end tests
```

## Dependency Rules

1. **ApplicationCore** → No dependencies (pure domain logic)
2. **Infrastructure** → References ApplicationCore only
3. **API/Web** → References ApplicationCore and Infrastructure
4. **Tests** → Can reference any project

---

# Section B: Command Implementation Guides

## Command: `/clean-arch:new`

When the user invokes this command, follow this workflow:

### Step 1: Gather Project Information

Use `AskUserQuestion` to gather:

```xml
<question 1>
Question: "What is your project name?"
Header: "Project Name"
Options:
- Enter custom name (text input)
Default: MySolution
</question>

<question 2>
Question: "Which API style do you prefer?"
Header: "API Style"
Options:
- FastEndpoints (Recommended for new projects)
- Minimal APIs (Lightweight, built-in)
- Controllers (Traditional MVC)
</question>

<question 3>
Question: "Which database will you use?"
Header: "Database"
Options:
- SQL Server (LocalDB for development)
- PostgreSQL
- In-Memory (for testing/prototyping)
</question>

<question 4>
Question: "Include authentication setup?"
Header: "Authentication"
Options:
- Yes, with JWT Bearer authentication
- Yes, with ASP.NET Identity
- No, I'll add it later
</question>
```

### Step 2: Generate Solution Structure

Create the directory structure and solution file:

```bash
mkdir -p src/ApplicationCore src/Infrastructure src/API tests/UnitTests tests/IntegrationTests

dotnet new sln -n {ProjectName}
dotnet new classlib -n ApplicationCore -o src/ApplicationCore
dotnet new classlib -n Infrastructure -o src/Infrastructure
dotnet new webapi -n API -o src/API
dotnet new xunit -n UnitTests -o tests/UnitTests
dotnet new xunit -n IntegrationTests -o tests/IntegrationTests

dotnet sln add src/ApplicationCore/ApplicationCore.csproj
dotnet sln add src/Infrastructure/Infrastructure.csproj
dotnet sln add src/API/API.csproj
dotnet sln add tests/UnitTests/UnitTests.csproj
dotnet sln add tests/IntegrationTests/IntegrationTests.csproj
```

### Step 3: Configure Project References

```bash
# Infrastructure depends on ApplicationCore
dotnet add src/Infrastructure/Infrastructure.csproj reference src/ApplicationCore/ApplicationCore.csproj

# API depends on both
dotnet add src/API/API.csproj reference src/ApplicationCore/ApplicationCore.csproj
dotnet add src/API/API.csproj reference src/Infrastructure/Infrastructure.csproj

# Tests depend on what they test
dotnet add tests/UnitTests/UnitTests.csproj reference src/ApplicationCore/ApplicationCore.csproj
dotnet add tests/IntegrationTests/IntegrationTests.csproj reference src/Infrastructure/Infrastructure.csproj
```

### Step 4: Add NuGet Packages

**ApplicationCore** (domain layer - minimal dependencies):
```bash
cd src/ApplicationCore
dotnet add package Ardalis.GuardClauses
dotnet add package Ardalis.Specification
dotnet add package Ardalis.Result
dotnet add package MediatR
```

**Infrastructure** (data access):
```bash
cd ../Infrastructure
dotnet add package Microsoft.EntityFrameworkCore.SqlServer  # or .Npgsql for PostgreSQL
dotnet add package Microsoft.EntityFrameworkCore.InMemory
dotnet add package Ardalis.Specification.EntityFrameworkCore
dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
```

**API** (presentation):
```bash
cd ../API

# If FastEndpoints chosen:
dotnet add package FastEndpoints
dotnet add package FastEndpoints.Swagger

# If Minimal APIs chosen: (no extra package needed)

# Common packages:
dotnet add package AutoMapper.Extensions.Microsoft.DependencyInjection
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
```

**Tests**:
```bash
cd ../../tests/UnitTests
dotnet add package NSubstitute
dotnet add package xunit
dotnet add package xunit.runner.visualstudio
dotnet add package coverlet.collector

cd ../IntegrationTests
dotnet add package Microsoft.EntityFrameworkCore.InMemory
dotnet add package xunit
```

### Step 5: Generate Base Code Files

Create the following files using the patterns in Section D:

**ApplicationCore**:
- `Entities/BaseEntity.cs`
- `Interfaces/IAggregateRoot.cs`
- `Interfaces/IRepository.cs`
- `Interfaces/IReadRepository.cs`

**Infrastructure**:
-