Copilot instructions

1# GitHub Copilot Instructions for Clean Architecture Template
2 
3## Project Overview
4This is a **Clean Architecture template** for .NET 9 that demonstrates Domain-Driven Design (DDD) patterns. It's a starter template, not a reference application - delete sample code once you understand the patterns.
5 
6## Architecture & Project Structure
7 
8### C# Conventions
9- Use standard Microsoft naming conventions
10- Use `PascalCase` for types and methods, `camelCase` for parameters and private fields
11- Use `I` prefix for interfaces (e.g., `IRepository`)
12- Use `Async` suffix for async methods (e.g., `GetByIdAsync`)
13- Prefix private fields with `_` (e.g., `_repository`)
14- Always use {} for blocks except single-line exits (e.g. `return`, `throw`)
15- Always keep single line blocks on one line (e.g., `if (x) return y;`)
16- Prefer primary constructors for required dependencies
17- Never use primary constructor parameters directly - always assign to private fields for clarity and testability
18 
19### Core Dependencies Flow
20- **Core** ← UseCases ← Infrastructure 
21- **Core** ← UseCases ← Web
22- Never allow Core to depend on outer layers
23 
24### Key Projects
25- **Core**: Domain entities, aggregates, value objects, specifications, interfaces
26- **UseCases**: Commands/queries (CQRS), Mediator handlers, application logic  
27- **Infrastructure**: EF Core, external services, email, file access
28- **Web**: FastEndpoints API, REPR pattern, validation
29 
30## Development Patterns
31 
32### API Endpoints (FastEndpoints + REPR)
33- One endpoint per file: `Create.cs`, `Update.cs`, `Delete.cs`, `GetById.cs`
34- Separate request/response/validator files: `Create.CreateRequest.cs`, `Create.CreateValidator.cs`
35- Use `Endpoint<TRequest, TResponse>` base class
36- Example: `src/Clean.Architecture.Web/Contributors/Create.cs`
37 
38### Domain Model (Core)
39- Entities use encapsulation - minimize public setters
40- Group related entities into Aggregates
41- Use Value Objects (e.g., `ContributorName.From()`)
42- Domain Events for cross-aggregate communication
43- Repository interfaces defined in Core, implemented in Infrastructure
44 
45### Use Cases (CQRS)
46- Commands for mutations, Queries for reads
47- Queries can bypass repository pattern for performance
48- Use Mediator (source generator) for command/query handling
49- Chain of responsibility for cross-cutting concerns (logging, validation)
50 
51### Validation Strategy
52- **API Level**: FluentValidation on request DTOs (FastEndpoints integration)
53- **Use Case Level**: Validate commands/queries (defensive coding)
54- **Domain Level**: Business invariants throw exceptions, assume pre-validated input
55 
56## Essential Commands
57 
58### Build & Test
59```bash
60dotnet build Clean.Architecture.slnx
61dotnet test Clean.Architecture.slnx
62```
63 
64### Entity Framework Migrations
65```bash
66# From Web project directory
67dotnet ef migrations add MigrationName -c AppDbContext -p ../Clean.Architecture.Infrastructure/Clean.Architecture.Infrastructure.csproj -s Clean.Architecture.Web.csproj -o Data/Migrations
68
69dotnet ef database update -c AppDbContext -p ../Clean.Architecture.Infrastructure/Clean.Architecture.Infrastructure.csproj -s Clean.Architecture.Web.csproj
70```
71 
72### Template Installation & Usage
73```bash
74dotnet new install Ardalis.CleanArchitecture.Template
75dotnet new clean-arch -o Your.ProjectName
76```
77 
78## Key Dependencies & Patterns
79 
80### Primary Libraries
81- **FastEndpoints**: API endpoints (replaced Controllers/Minimal APIs)
82- **Mediator**: Command/query handling in UseCases
83- **EF Core**: Data access (SQLite default, easily changed to SQL Server)
84- **Ardalis.Specification**: Repository query specifications
85- **Ardalis.Result**: Error handling pattern
86- **Serilog**: Structured logging
87 
88### Central Package Management
89- All package versions in `Directory.Packages.props`
90- Use `<PackageReference Include="..." />` without Version attribute
91 
92### Test Organization
93- **UnitTests**: Core business logic, use cases
94- **IntegrationTests**: Database, infrastructure components  
95- **FunctionalTests**: API endpoints (subcutaneous testing)
96- Use `Microsoft.AspNetCore.Mvc.Testing` for API tests
97 
98## File Organization Conventions
99 
100### Web Project Structure
101```
102Contributors/
103  Create.cs                    # Endpoint
104  Create.CreateRequest.cs      # Request DTO
105  Create.CreateResponse.cs     # Response DTO  
106  Create.CreateValidator.cs    # FluentValidation
107  Update.cs, Delete.cs, etc.
108```
109 
110### Sample vs Template
111- `/sample` folder: Complete working example (NimblePros.SampleToDo)
112- `/src` folder: Clean template ready for your project
113- Study sample for patterns, use src for new projects
114 
115## Common Gotchas
116 
117- Don't include hyphens in project names (template limitation)
118- Replace `Ardalis.SharedKernel` with your own shared kernel
119- Database path in `appsettings.json` for SQLite
120- Use absolute paths in EF migration commands
121- FastEndpoints uses different validation approach than Controller-based APIs
122 
123## VS Code Tasks
124Use the predefined tasks: `build`, `publish`, `watch` instead of manual `dotnet` commands when possible.
125