backend-conventions

Backend Conventions (.NET 10 / C# 13)

Project Structure

src/backend/
├── MyProject.Shared/              # Result, Error, ErrorType, ErrorMessages (zero deps)
├── MyProject.Domain/Entities/     # Business entities (BaseEntity)
├── MyProject.Application/         # Interfaces, DTOs, service contracts
│   ├── Features/{Feature}/I{Feature}Service.cs
│   ├── Features/{Feature}/Dtos/{Operation}Input.cs, {Entity}Output.cs
│   ├── Identity/IUserService.cs, IUserContext.cs
│   └── Identity/Constants/AppRoles.cs, AppPermissions.cs
├── MyProject.Infrastructure/      # Implementations (all internal)
│   ├── Features/{Feature}/Services/, Configurations/, Extensions/
│   └── Persistence/MyProjectDbContext.cs
├── MyProject.ServiceDefaults/     # Aspire shared: OTEL, service discovery, resilience
├── MyProject.AppHost/             # Aspire orchestrator (local dev only)
└── MyProject.WebApi/              # Entry point
    ├── Features/{Feature}/{Feature}Controller.cs, {Feature}Mapper.cs
    ├── Features/{Feature}/Dtos/{Operation}/{Operation}Request.cs + Validator
    ├── Authorization/             # RequirePermission, PermissionPolicyProvider
    └── Shared/                    # ApiController, ProblemFactory, ValidationConstants

C# Conventions

Access Modifiers

Key Rules

• Nullability: string.Empty for required, string? for optional. Express nullability in the type system.
• Collections: Prefer IReadOnlyList<T> on public interfaces. Avoid exposing List<T> or T[] directly.
• Time: TimeProvider registered as TimeProvider.System singleton.
• NuGet: To add a package: <PackageVersion Include="Pkg" Version="X.Y.Z" /> in Directory.Packages.props, <PackageReference Include="Pkg" /> in .csproj.

Entity Definition

New entities should extend BaseEntity (provides Id, CreatedAt/By, UpdatedAt/By, IsDeleted, DeletedAt/By - all set by AuditingInterceptor automatically) and use BaseEntityRepository<T> for data access.