Instruction file imported from attrectomma/SimpleCADDDSample (.github/instructions/scaffolding.instructions.md). Copyright stays with the author.

Scaffolding a New Project

This instruction is for one-time project scaffolding or adding a complete new aggregate across all layers. For the full reference with every file template, see scaffolding.md at the repository root.

New Project Setup

Scaffold a single-project ASP.NET Core Web API with:

• EF Core + PostgreSQL
• Clean Architecture by folder boundaries (Domain → Data → Services → Endpoints)
• DDD tactical patterns (strongly typed IDs, value objects, sealed class entities)
• FluentValidation at endpoint boundary
• GlobalExceptionHandler for domain exceptions → ProblemDetails
• OpenAPI + Scalar (root / redirects to /scalar/v1)
• Docker Compose with PostgreSQL
• Integration tests with Testcontainers

Program.cs Template

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

// IUnitOfWork resolves the already-scoped ApplicationDbContext.
// Do NOT use AddScoped<IUnitOfWork, ApplicationDbContext>() — that creates a second instance.
builder.Services.AddScoped<IUnitOfWork>(sp =>
    sp.GetRequiredService<ApplicationDbContext>());

builder.Services.AddScoped<IItemQueries, DbContextItemQueries>();
builder.Services.AddValidatorsFromAssemblyContaining<Program>();

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseExceptionHandler();
app.MapOpenApi();
app.MapScalarApiReference();
app.MapGet("/", () => Results.Redirect("/scalar/v1")).ExcludeFromDescription();
app.UseHttpsRedirection();

// Map endpoints
app.MapCreateItemEndpoint();
app.MapGetItemByIdEndpoint();

app.Run();

public partial class Program { }

Adding a New Aggregate (Full Checklist)

1. Domain/{Aggregate}/{AggregateId}.cs — readonly record struct wrapping Guid
2. Domain/{Aggregate}/{ValueObjects}.cs — value objects for properties
3. Domain/{Aggregate}/{Aggregate}.cs — sealed class with static Create(...)
4. Data/{Aggregate}/{AggregateConfiguration}.cs — IEntityTypeConfiguration with HasConversion
5. Data/{Aggregate}/ApplicationDbContext{Aggregate}.cs — partial implementing IRepository
6. Data/ApplicationDbContext.cs — add : IRepository<Agg, AggId> + ApplyConfiguration
7. Data/{Aggregate}/I{Aggregate}Queries.cs — read-side interface with DTOs
8. Data/{Aggregate}/DbContext{Aggregate}Queries.cs — query implementation
9. Endpoints/{Aggregate}/ — endpoint files (Create, GetById, List, etc.)
10. Program.cs — wire queries + map endpoints
11. EF migration
12. Integration tests in tests/.../Endpoints/{Aggregate}/

Adding a Cross-Aggregate Service

1. Services/{Feature}/I{Feature}Service.cs — interface
2. Services/{Feature}/{Feature}Service.cs — implementation
3. Endpoints/{Feature}/{Action}Endpoint.cs — calls service
4. Program.cs — wire service

Adding a Child Entity to an Existing Aggregate

1. Domain/{Aggregate}/{ChildId}.cs — strongly typed ID
2. Domain/{Aggregate}/{Child}.cs — internal constructor + factory
3. Modify aggregate root — backing list + Add/Remove methods
4. Data/{Aggregate}/{AggregateConfiguration}.cs — add OwnsMany
5. Data/{Aggregate}/ApplicationDbContext{Aggregate}.cs — add .Include()
6. EF migration
7. Query interface — add child DTO + query method
8. Query implementation
9. New endpoint files for add / remove / list children
10. Wire endpoints in Program.cs
11. Integration tests