Verspakketten-API/Lutra/.github/copilot-instructions.md

# Copilot Instructions for Lutra

Use these standards when generating or modifying code in this repository.

## Project overview

- Target framework: .NET 10 (`net10.0`)
- Architecture: Clean Architecture
- Solution layers:
  - `Lutra.Domain`
  - `Lutra.Application`
  - `Lutra.Infrastructure.Sql`
  - `Lutra.API`
  - `Lutra.AppHost`
  - `Lutra.Infrastructure.Migrator`
  - `Lutra.Application.UnitTests` — xUnit unit tests for Application handlers
  - integration tests for API behavior (`Lutra.API.IntegrationTests`)
- Database: PostgreSQL via EF Core
- Orchestration: .NET Aspire
- Messaging pattern: `Cortex.Mediator` for CQRS handling

## General standards

- Prefer small, focused changes.
- Follow existing naming, formatting, and folder conventions.
- Keep dependencies pointing inward:
  - Domain depends on nothing
  - Application depends on Domain
  - Infrastructure depends on Application and Domain
  - API depends on Application and Infrastructure
  - AppHost and Migrator are host projects only
- Use nullable reference types correctly and keep implicit usings compatible with the project style.

## Clean Architecture guidance

Use Jason Taylor’s CleanArchitecture project as a reference for intent and structure, but adapt to this codebase’s actual implementation.

Where the reference template uses MediatR, this project uses `Cortex.Mediator`.
The established test stack is **xUnit** with **FluentAssertions** — both are already in use and should be used for all new tests.
Add FluentValidation, AutoMapper, Shouldly, Moq, or Respawn only if the repository already uses them or the change clearly requires them.

## Domain layer rules

- Keep entities simple and focused on business state.
- Use `BaseEntity` as the shared base type when appropriate.
- Preserve the current entity style:
  - `Id` as `Guid`
  - audit fields like `CreatedAt`, `ModifiedAt`, `DeletedAt`
  - `IsDeleted` as a derived property
- Keep validation and persistence concerns out of Domain unless they are intrinsic business rules.

## Application layer rules

- Put use cases in feature folders.
- Follow the existing CQRS split:
  - `FeatureName.cs` as the partial entry point
  - `FeatureName.Query.cs` or `FeatureName.Command.cs`
  - `FeatureName.Handler.cs`
  - `FeatureName.Response.cs`
- Use `Cortex.Mediator` request and handler interfaces.
- Keep handlers focused on orchestration and application logic.
- Use `ILutraDbContext` rather than referencing the concrete DbContext directly when possible.
- Shared model types (DTOs, enums) that are not use-case-specific live in `Models/<FeatureArea>/` (e.g., `Models/Verspakketten/`, `Models/Supermarkten/`).

## Infrastructure rules

- Put EF Core implementation, migrations, and database wiring in `Lutra.Infrastructure.Sql`.
- Keep the DbContext implementation aligned with `ILutraDbContext`.
- If package versions must be pinned for runtime compatibility, pin them explicitly in the infrastructure project.
- Be cautious with `PrivateAssets="all"` on design-time packages because they do not flow dependency constraints to downstream projects.

## API layer rules

- Keep controllers thin.
- Controllers should delegate to Application use cases through `IMediator`.
- Keep `Program.cs` focused on DI and middleware setup.

## Aspire and migration rules

- Keep `Lutra.AppHost` responsible for orchestration only.
- Preserve the persistent PostgreSQL container setup unless a change explicitly requires otherwise.
- Keep the migrator as a one-shot project that applies migrations on startup.
- Ensure migration-related changes do not break runtime assembly/version consistency.

## Naming and code style

- Use English for general code names (variables, method names, namespaces, folders) and use Dutch only for domain-specific enums, types, and files that reflect business concepts (e.g., `Verspakketten`, `Supermarkt`, `Beoordeling`).
- Keep class and file names consistent with the feature name.
- Use sealed types where the project already does.
- Prefer explicit `required` members where the current codebase uses them.
- Always use **file-scoped namespaces** (`namespace Foo.Bar;`), never block-scoped (`namespace Foo.Bar { }`).
- Preserve current indentation and brace style in each file.

## Testing guidance

- If tests exist, update or add tests alongside behavior changes.
- Follow the reference template's intent for test coverage:
  - unit tests for business logic (`Lutra.Application.UnitTests`)
  - integration tests for API behavior (`Lutra.API.IntegrationTests`)
- Test framework: **xUnit** (`xunit` v2 + `xunit.runner.visualstudio`).
- Assertions: **FluentAssertions**.
- Integration tests use **SQLite** (via `Microsoft.EntityFrameworkCore.Sqlite`) as the in-process test database -- not PostgreSQL. Use `LutraApiFactory` and `IntegrationTestBase` as the base infrastructure.
- Keep tests readable and focused on behavior.

## When making changes

- Read the relevant file before editing.
- Make the smallest change that solves the problem.
- Reuse existing patterns from the repo instead of inventing new ones.
- Run or request a build/test verification after changes when appropriate.
- Avoid broad refactors unless the user asks for them.

## Available agents

Specialist agents for common tasks are in `.github/agents/`. Invoke them when the task matches:

| Agent file | When to use |
|---|---|
| `csharp-expert.agent.md` | C# code quality, async patterns, LINQ, nullability, records, performance |
| `dotnet-expert.agent.md` | .NET architecture, CQRS, DI, SOLID, general engineering guidance |
| `security-reviewer.agent.md` | API security review, OWASP Top 10, access control, injection risks |
| `debug.agent.md` | Diagnosing and fixing bugs systematically |
| `postgresql-dba.agent.md` | PostgreSQL queries, schema, migrations, performance |
| `test-generator.agent.md` | Generating unit, integration, or functional tests for any layer |