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
• 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. Add FluentValidation, AutoMapper, NUnit, 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.

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.
• 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
  • integration tests for infrastructure and data access
  • functional tests for API behavior
• 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