If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jasontaylordev/CleanArchitecture shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 3 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jasontaylordev/CleanArchitecture repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jasontaylordev/CleanArchitecture.

What it runs against: a local clone of jasontaylordev/CleanArchitecture — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jasontaylordev/CleanArchitecture | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jasontaylordev/CleanArchitecture. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jasontaylordev/CleanArchitecture.git
#   cd CleanArchitecture
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jasontaylordev/CleanArchitecture and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jasontaylordev/CleanArchitecture(\\.git)?\\b" \\
  && ok "origin remote is jasontaylordev/CleanArchitecture" \\
  || miss "origin remote is not jasontaylordev/CleanArchitecture (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/Application/DependencyInjection.cs" \\
  && ok "src/Application/DependencyInjection.cs" \\
  || miss "missing critical file: src/Application/DependencyInjection.cs"
test -f "src/Domain/Common/BaseEntity.cs" \\
  && ok "src/Domain/Common/BaseEntity.cs" \\
  || miss "missing critical file: src/Domain/Common/BaseEntity.cs"
test -f "src/Application/Common/Interfaces/IApplicationDbContext.cs" \\
  && ok "src/Application/Common/Interfaces/IApplicationDbContext.cs" \\
  || miss "missing critical file: src/Application/Common/Interfaces/IApplicationDbContext.cs"
test -f "src/AppHost/Program.cs" \\
  && ok "src/AppHost/Program.cs" \\
  || miss "missing critical file: src/AppHost/Program.cs"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jasontaylordev/CleanArchitecture"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A production-ready .NET template for building enterprise ASP.NET Core applications following Clean Architecture principles. It generates a complete solution with a domain layer, application layer with MediatR commands/queries, infrastructure layer with Entity Framework Core, and a choice of Angular/React/Web API frontend—all wired with Aspire for orchestration and containerization. Monorepo structure with src/AppHost (Aspire orchestration), src/Application (MediatR handlers and behaviours in src/Application/Common), infrastructure layers, and multiple frontend templates. Solutions are generated on-demand via dotnet new ca-sln parametrized by client framework (Angular/React/none) and database (PostgreSQL/SQLite/SQL Server), making it a template-driven architecture.

Enterprise .NET developers and architects who need a scalable, well-structured starting point for new ASP.NET Core projects and want to enforce separation of concerns, dependency injection, and CQRS patterns from day one without building boilerplate.

Production-ready. The project has 7.8k+ GitHub stars, active CI/CD pipelines (build.yml, codeql.yml, release.yml), comprehensive test coverage via BDD (Gherkin tests), and architectural decision records (ADRs) documenting key choices. Latest .NET 10.0 SDK support and regular NuGet package updates indicate active maintenance.

Low risk for core template stability; the repo is well-established with documented ADRs and strong CI coverage. Minor risk: single-maintainer (jasontaylordev) for core repo, though it's a template consumed by many projects. Depends on third-party services (Docker/Podman, SQL providers, Aspire runtime) which may have breaking changes—mitigated by flexible database options (SQLite, PostgreSQL, SQL Server).

Active development targeting .NET 10.0; recent changes include Aspire integration for orchestration/testing (ADR-002), MediatR contract patterns in domain layer (ADR-003), and EFCore placement in application layer (ADR-001). Template supports modern frontend stacks (React 19, TypeScript 5.9, Vite) and includes renovate.json for dependency automation.

# Install template
dotnet new install Clean.Architecture.Solution.Template

# Create new solution (example: React + PostgreSQL)
dotnet new ca-sln --client-framework react --database postgresql --output MyProject

# Navigate and run
cd MyProject
dotnet run --pr

Daily commands:

# Backend
dotnet run --pr

# Frontend (if Angular/React selected; from web directory)
npm install
npm run prestart  # generates API client
npm start         # Vite dev server

• src/Application/DependencyInjection.cs — Core DI setup for the Application layer—registers all MediatR handlers, behaviors, and validators that implement Clean Architecture pipelines.
• src/Domain/Common/BaseEntity.cs — Base domain entity class defining the core entity abstraction; all domain models inherit from this, making it foundational to domain-driven design.
• src/Application/Common/Interfaces/IApplicationDbContext.cs — Contract for EF Core database access; the critical boundary between Application and Infrastructure layers enabling testability and persistence abstraction.
• src/AppHost/Program.cs — ASP.NET Core Aspire orchestration entry point; defines service configuration, middleware, and container composition for the entire application.
• Directory.Build.props — Centralized MSBuild properties for all projects; controls versioning, analyzers, and SDK settings across the entire solution.
• .template.config/template.json — NuGet template metadata defining how this solution is packaged and instantiated; essential for understanding the template-based distribution model.
• src/Application/Common/Behaviours/ValidationBehaviour.cs — MediatR pipeline behavior implementing cross-cutting validation concern; exemplifies the middleware pattern central to Clean Architecture request handling.

Add a new domain entity with commands and queries

1. Create a new domain entity class inheriting from BaseAuditableEntity in src/Domain/[Feature]/[Entity].cs (src/Domain/Common/BaseAuditableEntity.cs)
2. Create a command handler in src/Application/[Feature]/Commands/Create[Entity]/Create[Entity].cs following the MediatR ICommandHandler<,> pattern (src/Application/TodoItems/Commands/CreateTodoItem/CreateTodoItem.cs)
3. Create a validator class [Entity]CommandValidator.cs using FluentValidation AbstractValidator<T> (src/Application/TodoItems/Commands/CreateTodoItem/CreateTodoItemCommandValidator.cs)
4. Create a query handler in src/Application/[Feature]/Queries/Get[Entities]/Get[Entities].cs implementing IRequestHandler<,> (src/Application/TodoLists/Queries/GetTodos/GetTodos.cs)
5. Register the new handlers and validators in src/Application/DependencyInjection.cs using MediatR.AddMediatR() and AddFluentValidationClientsideAdapters() (src/Application/DependencyInjection.cs)

Add a cross-cutting concern via MediatR pipeline behavior

1. Create a new behavior class in src/Application/Common/Behaviours/[Concern]Behaviour.cs implementing IPipelineBehavior<,> (src/Application/Common/Behaviours/PerformanceBehaviour.cs)
2. Implement the Handle method to wrap the next handler; add logic before/after await next() (src/Application/Common/Behaviours/UnhandledExceptionBehaviour.cs)
3. Register in src/Application/DependencyInjection.cs via services.AddTransient(typeof(IPipelineBehavior<,>), typeof([Concern]Behaviour)) (src/Application/DependencyInjection.cs)

Add domain event handling and publishing

1. Create a domain event class in src/Domain/[Feature]/Events/[Entity][Action]Event.cs inheriting from BaseEvent (src/Domain/Common/BaseEvent.cs)
2. Raise the event from an entity method via base.AddDomainEvent(new MyEvent(...)) (src/Domain/Common/BaseAuditableEntity.cs)
3. Create an event handler in src/Application/[Feature]/EventHandlers/[Entity][Action]Handler.cs implementing INotificationHandler<> (src/Application/TodoItems/EventHandlers/LogTodoItemCompleted.cs)
4. In the command handler or infrastructure layer, publish events via mediator.Publish(domainEvent) after saving changes (src/Application/Common/Behaviours/LoggingBehaviour.cs)

Regenerate React API client from Swagger

1. Ensure the ASP.NET Core API exposes a Swagger/OpenAPI endpoint (typically /swagger/v1/swagger.json) (src/AppHost/Program.cs)
2. Update the API URL in package.json or nswag configuration to point to your API (package.json)
3. Run npm run generate-api (defined in package.json scripts) to invoke nswag and regenerate the TypeScript client (package.json)

• Clean Architecture (Domain → Application → Presentation) — Enforces separation of concerns, isolates business logic from infrastructure, and enables testability and maintainability across layers.
• MediatR for CQRS — Decouples command/query handlers from controllers; enables easy middleware injection (validation, logging, authorization) via pipeline behaviors.
• EF Core in Application Layer — Direct EF Core usage (vs. Repository pattern) reduces boilerplate; IApplicationDbContext abstraction allows infrastructure implementation flexibility.
• FluentValidation — Declarative, reusable validation rules; integrates seamlessly with MediatR pipeline for automatic request validation.
• ASP.NET Core Aspire — Orchestrates multi-project debugging, container deployment, and service discovery in a single app host; simplifies local dev-to-prod parity.
• React 19 + TypeScript + Vite — Modern SPA stack with strong typing; Vite provides fast dev iteration; auto-generated API client from Swagger ensures type-safe backend integration.
• NuGet Template Distribution — undefined

Template generation quirks: The --client-framework and --database parameters are case-sensitive and limited to specific values (angular/react/none, postgresql/sqlite/sqlserver); typos will fail silently. NSwag setup: Frontend apps expect nswag run /runtime:Net100 in npm prestart; if .NET SDK version mismatches, client generation fails. Docker requirement: SQL Server and PostgreSQL templates require Docker Desktop or Podman running; SQLite is the only option without container runtime. Aspire service discovery: AppHost expects specific service names (e.g., 'api', 'web'); custom names require manual launchSettings.json updates. EFCore in Application layer: Unlike traditional Clean Architecture, EFCore is intentionally placed in Application layer (not Infrastructure); migrations and DbContext design reflect this.

• Clean Architecture Layers — The template enforces strict layering (Domain → Application → Infrastructure → Presentation) to ensure business logic is isolated, testable, and independent of frameworks; understanding layer responsibilities is fundamental to extending the template correctly
• CQRS (Command Query Responsibility Segregation) — The template uses MediatR to separate write operations (Commands) from read operations (Queries), enabling independent scaling and validation strategies; critical for understanding request flow in src/Application/
• MediatR Pipeline Behaviours — Behaviours in src/Application/Common/Behaviours/ inject cross-cutting concerns (logging, authorization) into every command/query without modifying handlers; understanding the pipeline is essential for adding new global policies
• Aspire Orchestration — AppHost coordinates service startup, networking, and container lifecycle; ADR-002 explains why it replaced manual Docker Compose; necessary to understand service discovery and local debugging
• Entity Framework Core in Application Layer — ADR-001 documents the non-traditional choice to place EFCore in Application layer rather than Infrastructure; affects how migrations, DbContext, and repository patterns are structured in this template
• Template Parametrization (.template.config) — The .template.config/ directory defines conditional file generation based on CLI parameters (client-framework, database); understanding symbol mapping is required to modify template variants or add new options
• NSwag Code Generation — Frontend npm prestart script runs nswag run /runtime:Net100 to auto-generate TypeScript API clients from OpenAPI spec; avoids manual API binding and keeps frontend in sync with backend changes

• ardalis/CleanArchitecture — Alternative Clean Architecture template also for ASP.NET Core; less opinionated on frontend choice, focuses on domain-driven design patterns
• kgrzybek/modular-monolith-with-ddd — Modular monolith variant of Clean Architecture with DDD; shows how to scale horizontally within single solution
• dotnet/aspire — Official Microsoft Aspire orchestration framework; the template uses it for service composition and testing (ADR-002)
• jbogard/MediatR — Core MediatR library used throughout template for CQRS command/query dispatch and pipeline behaviours
• jasontaylordev/CleanArchitecture.BlazorServer — Same author's Blazor variant of Clean Architecture; alternative to Angular/React for UI layer using server-rendered components

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for MediatR pipeline behaviors

The repo implements custom MediatR behaviors (AuthorizationBehaviour, LoggingBehaviour, PerformanceBehaviour, UnhandledExceptionBehaviour, ValidationBehaviour) in src/Application/Common/Behaviours/ but there's no visible test coverage for these critical cross-cutting concerns. Integration tests would validate that behaviors execute in correct order, handle exceptions properly, and enforce authorization checks. This is essential for a Clean Architecture template.

• [ ] Create src/Tests/Application.Tests/Common/Behaviours/ directory structure
• [ ] Add unit tests for each behavior in src/Application/Common/Behaviours/ (5 behavior files)
• [ ] Test authorization behavior with authorized and unauthorized claims
• [ ] Test validation behavior with ValidationException scenarios
• [ ] Test performance behavior logging threshold
• [ ] Test unhandled exception behavior error handling
• [ ] Add tests to CI pipeline in .github/workflows/build.yml if not already covered

Add E2E tests for React frontend API integration with nswag-generated client

The frontend uses nswag to auto-generate API clients (npm script 'generate-api' in package.json), but there are no visible E2E tests validating the generated client works with the actual backend. This is critical for a full-stack template. Tests should verify the generated API client contracts match backend endpoints and handle responses correctly.

• [ ] Create src/Web/src/tests/e2e/ directory for E2E tests
• [ ] Add setup for Playwright or Cypress that runs against AppHost (src/AppHost/)
• [ ] Test generated client initialization and API calls to TodoItems endpoints
• [ ] Verify request/response serialization from nswag-generated types
• [ ] Add CI workflow step in .github/workflows/build.yml to run E2E tests against running AppHost
• [ ] Document nswag generation and client usage in README.md or docs/

Add Application layer specification tests for command/query contracts

The repo references MediatR contracts in the domain (ADR-003) and has TodoItems commands/queries (src/Application/TodoItems/Commands/), but no visible tests validating request/response contracts, validators, or handler behavior. Specification-style tests would document expected behavior and catch breaking changes to contracts.

• [ ] Create src/Tests/Application.Tests/TodoItems/ directory
• [ ] Add specification tests for CreateTodoItem command (src/Application/TodoItems/Commands/CreateTodoItem/)
• [ ] Add tests for TodoItem queries and their result DTOs
• [ ] Test FluentValidation rules for each command/query validator
• [ ] Test handler success, validation failure, and authorization failure scenarios
• [ ] Ensure tests are discoverable and run in .github/workflows/build.yml

• Add integration tests for all MediatR behaviours in src/Application/Common/Behaviours/ (currently no test files visible for LoggingBehaviour.cs and AuthorizationBehaviour.cs)
• Document the Aspire orchestration flow in ADR-002 with a diagram showing service connectivity; currently explains decision but lacks visual topology reference
• Create template variant for MAUI desktop client (parallel to Angular/React options); would require new .template.config conditional and src/Maui/ project structure

• High · Unrestricted nswag Dependency Version — package.json - devDependencies. The package.json specifies 'nswag': 'latest' which pins to the latest version without version constraints. This can introduce breaking changes and security vulnerabilities in automated builds and deployments. The nswag tool is used for API code generation and should have controlled versioning. Fix: Replace 'latest' with a specific pinned version (e.g., '^8.0.0' or exact version). Implement dependency lock files (package-lock.json) and review nswag releases regularly for security patches.
• Medium · Missing package-lock.json or Yarn Lock File — Repository root. No lock file is visible in the provided structure. This creates supply chain security risks as npm dependencies may resolve to different versions across environments, potentially pulling vulnerable versions during installation. Fix: Commit package-lock.json (npm) or yarn.lock (yarn) to version control. Ensure all developers and CI/CD pipelines use 'npm ci' instead of 'npm install' for reproducible builds.
• Medium · Outdated Type Definitions — package.json - devDependencies. @types/node is pinned to '^24.0.0' which may be ahead of the actual Node.js runtime version being used. This can cause type mismatches and security issues if type definitions don't match runtime behavior. Fix: Verify that @types/node version matches the target Node.js LTS version being used in production. Pin to a specific version or use a tighter constraint based on your Node.js version.
• Medium · Missing Security Headers Configuration — src/Application, src/Infrastructure (inferred missing). The file structure shows no explicit security configuration files (e.g., security.txt, CNAME for CORS, CSP configuration) for the ASP.NET Core backend. API endpoints may be vulnerable to CSRF, clickjacking, and other attacks without proper headers. Fix: Implement security headers middleware in the ASP.NET Core application: X-Frame-Options, X-Content-Type-Options, Content-Security-Policy, Strict-Transport-Security, and X-XSS-Protection headers.
• Medium · No Visible Input Validation Configuration — src/Application/TodoItems/Commands, src/Application/TodoLists/Commands. While validators exist (CreateTodoItemCommandValidator.cs, UpdateTodoItemCommandValidator.cs), there's no evidence of global input validation, rate limiting, or CORS configuration visible in the provided structure. Fix: Ensure CORS is properly configured with specific allowed origins (not '*'). Implement rate limiting on API endpoints. Validate all user inputs at both client and server levels.
• Low · Vite Build Tool Configuration Not Audited — Repository root (vite.config.* assumed missing or not shown). Vite configuration file (vite.config.ts/js) is not visible in the provided structure. Potential misconfiguration could expose source maps in production or serve files with incorrect security headers. Fix: Ensure vite.config.ts has proper production configuration: disable source maps in production, set correct base path, and avoid exposing sensitive information.
• Low · GitHub Actions Workflows Not Fully Visible — .github/workflows/. CI/CD workflow files (build.yml, test-templates.yml, release.yml) are present but content is not provided. Workflows could potentially have secrets management issues or insecure artifact handling. Fix: Audit all workflow files for: proper secret handling (using GitHub Secrets, not hardcoded), signed commits, secure artifact storage, and minimal permissions principle for CI runners.
• Low · Missing SAST and Dependency Scanning Configuration — .github/workflows/, renovate.json. While CodeQL workflow exists, there's no visible evidence of dependency scanning tools (Dependabot, Snyk) or OWASP dependency-check in the configuration. Fix: Enable Dependabot in repository settings for automated dependency vulnerability scanning. Consider adding OWASP dependency-check to CI/CD pipeline for comprehensive SCA.
• Low · No Visible API Authentication Configuration — undefined. While Authorize Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.