ASP.NET Core Backend

Optimized for Layered Architecture — dependencies flow inward: Api → Core → Persistence.

Project Structure

src/
  Api/
    Attributes/
    Authorization/
    Controllers/
    Extensions/
      Http/
        ResponseEnvelope      # Wraps all responses
        ResponseResultExecutor
      ServiceExtensions.cs    # DI registrations
    Swagger/
      ResponseEnvelopeOperationFilter
    Validators/
    Jobs/                     # Quartz cron jobs
  Core/
    Configurations/
    Dtos/
    Request/
    Response/
    Enums/
    Services/                 # Business logic (DTOs in/out)
  Persistence/
    Enums/
    Models/                   # EF Core entities
  Migrations/
    Migrations/               # EF Core migration files
    Scripts/                  # SQL scripts (same name as migration, .sql ext)

Key Workflows

Creating a New Endpoint

1. Define request/response DTOs in Core/Dtos/, Core/Request/, or Core/Response/
2. Create or extend a service in Core/Services/ (DTOs as params, not EF models)
3. Add model-to-DTO mapping as extension methods for reusability
4. Create validator using FluentValidation in Api/Validators/
5. Add controller action with:
   • [FromServices] validator injection (not constructor)
   • CancellationToken parameter passed through the whole chain
   • ProducesResponseType<T>(StatusCodes.StatusXXX) annotations (use enum, not magic numbers)
   • No try-catch (ErrorHandlerMiddleware handles exceptions)
6. Register new services in Api/Extensions/ServiceExtensions.cs

Database Migrations

Never create migration files manually. Use the bundled script:

./scripts/generate-migration.sh <MigrationName>

The script runs dotnet ef migrations add and generates a matching SQL script automatically. It auto-detects the src/ directory. Override with env vars if needed:

Pass --context <Name> to specify a DbContext explicitly.

Error Handling Pattern

• Controllers: No try-catch. ErrorHandlerMiddleware handles everything.
• Services: Catch unexpected exceptions, log, re-throw as AppException with inner exception.
• Validation: Throw InputException for invalid input. Validators injected via [FromServices].

Response Envelope

All responses are wrapped in ResponseEnvelope<T> by middleware. Controllers return unwrapped types. The ResponseEnvelopeOperationFilter embeds the envelope in Swagger output so auto-generated clients work without patching.

Detailed References

• Coding guidelines (style, naming, error handling, DI, testing, security): See references/coding-guidelines.md
• API design (controllers, response types, Swagger, versioning): See references/api-design.md