siesa-agents 2.1.39 → 2.1.41

package/bmad/bmm/workflows/3-solutioning/create-architecture/data/company-standards/backend-standards.md

@@ -0,0 +1,812 @@
+# Backend Development Standards
+
+> **Note**: For architecture patterns and principles (Clean Architecture, DDD, folder structure), see [architecture-patterns.md](./architecture-patterns.md)
+
+## Technology Stack Standards
+
+### Core Technologies
+- **.NET 10**: Main framework with C#
+- **C# Minimal API**: Lightweight and modern approach for APIs
+- **Entity Framework Core 10**: ORM for database operations
+- **xUnit**: Unit and integration testing framework
+- **FluentValidation**: Validation for DTOs and models
+
+### Framework Standards
+- **Default Framework**: .NET 10 with C# Minimal API
+- **Database**: PostgreSQL with Entity Framework Core 10 (mandatory)
+- **ORM Extensions**: 
+  - **linq2db**: For highly optimized complex queries requiring maximum performance
+  - **DynamicLinq**: For runtime dynamic filters from user input or configurable scenarios
+  - **LinqKit**: For composable type-safe predicates in DDD repositories with complex business rules
+- **Testing**: TDD approach with xUnit and high test coverage
+- **Documentation**: Scalar (NO Swagger) auto-generated
+- **Primary Keys**: UUID (Guid) for all entities
+
+## CRITICAL: DateTime Type Standards
+
+### ⚠️ Mandatory Rule: Use DateTimeOffset for Timestamps
+
+**ALWAYS use `DateTimeOffset` instead of `DateTime`** for all timestamp fields in entities, DTOs, and database models.
+
+#### Why DateTimeOffset?
+
+- **PostgreSQL Compatibility**: PostgreSQL uses `TIMESTAMP WITH TIME ZONE` which maps correctly to `DateTimeOffset` but NOT to `DateTime`
+- **Timezone Awareness**: `DateTimeOffset` preserves timezone information, preventing timezone conversion issues
+- **UTC Consistency**: Store all timestamps in UTC for consistency across different timezones
+- **Avoiding Bugs**: Using `DateTime` with PostgreSQL causes:
+  - Data loss during timezone conversions
+  - Inconsistent timestamp comparisons
+  - Ambiguous datetime values during DST transitions
+
+#### Correct Usage
+
+```csharp
+// ✅ CORRECT - Use DateTimeOffset for timestamps
+public class UserEntity : AggregateRoot
+{
+    public Guid Id { get; private set; }
+    public string Email { get; private set; }
+    public DateTimeOffset CreatedAt { get; private set; } = DateTimeOffset.UtcNow;
+    public DateTimeOffset UpdatedAt { get; private set; } = DateTimeOffset.UtcNow;
+}
+
+// ✅ CORRECT - Use DateOnly for date-only fields
+public class ExpenseEntity : AggregateRoot
+{
+    public Guid Id { get; private set; }
+    public decimal Amount { get; private set; }
+    public DateOnly ExpenseDate { get; private set; } // Date without time
+    public DateTimeOffset CreatedAt { get; private set; } = DateTimeOffset.UtcNow;
+}
+
+// ❌ WRONG - Never use DateTime for timestamp fields
+public class UserEntity : AggregateRoot
+{
+    public DateTime CreatedAt { get; private set; } // ❌ WRONG - causes PostgreSQL issues
+    public DateTime UpdatedAt { get; private set; } // ❌ WRONG - causes PostgreSQL issues
+}
+```
+
+#### Entity Framework Core Configuration
+
+```csharp
+public class UserEntityConfiguration : IEntityTypeConfiguration<UserEntity>
+{
+    public void Configure(EntityTypeBuilder<UserEntity> builder)
+    {
+        builder.ToTable("users");
+
+        // DateTimeOffset fields - automatically map to TIMESTAMP WITH TIME ZONE
+        builder.Property(u => u.CreatedAt)
+            .IsRequired()
+            .HasDefaultValueSql("NOW()"); // PostgreSQL auto-generates UTC timestamp
+
+        builder.Property(u => u.UpdatedAt)
+            .IsRequired()
+            .HasDefaultValueSql("NOW()");
+    }
+}
+```
+
+#### Type Selection Guide
+
+| Use Case | Type | Example |
+|----------|------|---------|
+| Timestamp with timezone | `DateTimeOffset` | `CreatedAt`, `UpdatedAt`, `DeletedAt`, `LastLoginAt` |
+| Date only (no time) | `DateOnly` | `BirthDate`, `ExpenseDate`, `DueDate` |
+| Time only (no date) | `TimeOnly` | `OpeningTime`, `ClosingTime` |
+| Never use | `DateTime` | ❌ Not compatible with PostgreSQL TIMESTAMP WITH TIME ZONE |
+
+#### Best Practices
+
+1. **Always use `DateTimeOffset`** for `CreatedAt`, `UpdatedAt`, and any timestamp field
+2. **Always use UTC**: Set values with `DateTimeOffset.UtcNow`
+3. **Configure EF Core**: Use `HasDefaultValueSql("NOW()")` for automatic timestamps
+4. **DTOs must match**: DTOs also use `DateTimeOffset` (serializes to ISO 8601 with timezone)
+5. **Never use `DateTime`** for entity timestamp fields in PostgreSQL projects
+
+### ORM Strategy Guidelines
+
+#### When to Use Entity Framework Core 10
+✔ **Primary ORM for:**
+- Standard CRUD operations
+- DDD entities with tracking (Aggregate Roots, Domain Events)
+- Simple to moderate queries
+- Navigation properties and relationships
+- Change tracking scenarios
+
+#### When to Use linq2db
+✔ **Use for maximum performance:**
+- Highly optimized complex queries (subqueries, complex projections, multiple joins)
+- Queries that EF Core cannot translate efficiently
+- High-performance endpoints: dashboards, analytics, reports, high data volumes
+- Pure queries without tracking needs
+- When EF Core generates inefficient SQL
+
+🚫 **Avoid when:**
+- Need complete DDD entities with aggregate lifecycle
+- Query participates in domain events or tracking
+
+#### When to Use DynamicLinq
+✔ **Use for runtime flexibility:**
+- Dynamic filter systems: `?filter=Age > 30 AND Country == "CO"`
+- Simplified OData-style APIs
+- Configurable grids or data explorers
+- Variable column searches
+
+🚫 **Avoid when:**
+- Filters are fully controlled in code
+- Require strict security (needs sanitization)
+- Need maximum performance (use linq2db or LinqKit)
+
+#### When to Use LinqKit
+✔ **Use for type-safe composition:**
+- Complex business rules in queries with composable predicates
+- Dynamic filters with type safety (no strings → expressions)
+- DDD repositories with multiple criteria, conditional searches, reusable queries
+- Enhance EF Core when composing complex expressions
+- 100% compatible with EF Core translation
+
+🚫 **Avoid when:**
+- Filters are extremely simple
+- Query is highly dynamic and text-based (use DynamicLinq)
+- Need maximum raw performance (use linq2db)
+
+### Development Tools
+- **dotnet CLI**: Project management, build, test, and restore
+- **NuGet**: Package manager
+- **EF Core 10 Migrations**: Database schema version control
+- **Docker**: For production only
+- **Code Analyzers**: Static C# code analysis
+- **EditorConfig**: Code formatting standards
+
+## Domain-Driven Design Implementation
+
+### Entity Structure
+```csharp
+public class UserEntity : AggregateRoot
+{
+    // Parameterless constructor for EF Core (materialization from DB)
+    private UserEntity() : base(Guid.Empty)
+    {
+        // EF Core needs this to reconstruct the entity from the database
+    }
+
+    private UserEntity(
+        Guid id,
+        EmailValueObject email,
+        NameValueObject name) : base(id)
+    {
+        Email = email;
+        Name = name;
+    }
+
+    public EmailValueObject Email { get; private set; } = null!;
+    public NameValueObject Name { get; private set; } = null!;
+
+    public static UserEntity Create(string email, string name)
+    {
+        var userEmail = EmailValueObject.Create(email);
+        var userName = NameValueObject.Create(name);
+        
+        var user = new UserEntity(Guid.NewGuid(), userEmail, userName);
+        user.AddDomainEvent(new UserCreatedEvent(user.Id));
+        
+        return user;
+    }
+
+    public void UpdateEmail(string newEmail)
+    {
+        var newEmailVO = EmailValueObject.Create(newEmail);
+        if (Email.Equals(newEmailVO)) return;
+        
+        Email = newEmailVO;
+        AddDomainEvent(new UserEmailUpdatedEvent(Id, Email));
+    }
+}
+```
+
+### Value Object Structure
+```csharp
+public class EmailValueObject : ValueObject
+{
+    public string Value { get; }
+
+    private EmailValueObject(string value)
+    {
+        Value = value;
+    }
+
+    public static EmailValueObject Create(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            throw new ArgumentException("Email cannot be empty", nameof(value));
+            
+        if (!IsValidEmail(value))
+            throw new InvalidEmailException(value);
+            
+        return new EmailValueObject(value);
+    }
+
+    private static bool IsValidEmail(string email)
+    {
+        // Email validation logic
+        return System.Text.RegularExpressions.Regex.IsMatch(
+            email, 
+            @"^[^@\s]+@[^@\s]+\.[^@\s]+$");
+    }
+
+    protected override IEnumerable<object> GetEqualityComponents()
+    {
+        yield return Value;
+    }
+}
+```
+
+### Repository Pattern
+```csharp
+// Interface (in Application layer)
+public interface IUserRepository
+{
+    Task<UserEntity> SaveAsync(UserEntity user, CancellationToken cancellationToken = default);
+    Task<UserEntity?> FindByIdAsync(Guid id, CancellationToken cancellationToken = default);
+    Task<UserEntity?> FindByEmailAsync(EmailValueObject email, CancellationToken cancellationToken = default);
+    Task DeleteAsync(Guid id, CancellationToken cancellationToken = default);
+}
+
+// Implementation (in Infrastructure layer)
+public class UserRepository : IUserRepository
+{
+    private readonly ApplicationDbContext _context;
+
+    public UserRepository(ApplicationDbContext context)
+    {
+        _context = context;
+    }
+
+    public async Task<UserEntity> SaveAsync(UserEntity user, CancellationToken cancellationToken = default)
+    {
+        var existingUser = await _context.Users.FindAsync(new object[] { user.Id }, cancellationToken);
+        
+        if (existingUser == null)
+            await _context.Users.AddAsync(user, cancellationToken);
+        else
+            _context.Users.Update(user);
+
+        await _context.SaveChangesAsync(cancellationToken);
+        return user;
+    }
+
+    public async Task<UserEntity?> FindByIdAsync(Guid id, CancellationToken cancellationToken = default)
+    {
+        return await _context.Users.FindAsync(new object[] { id }, cancellationToken);
+    }
+
+    public async Task<UserEntity?> FindByEmailAsync(EmailValueObject email, CancellationToken cancellationToken = default)
+    {
+        return await _context.Users
+            .FirstOrDefaultAsync(u => u.Email.Value == email.Value, cancellationToken);
+    }
+
+    public async Task DeleteAsync(Guid id, CancellationToken cancellationToken = default)
+    {
+        var user = await FindByIdAsync(id, cancellationToken);
+        if (user != null)
+        {
+            _context.Users.Remove(user);
+            await _context.SaveChangesAsync(cancellationToken);
+        }
+    }
+}
+```
+
+## Command/Query (CQRS) Standards
+
+### Command Structure
+```csharp
+public record CreateUserCommand(string Email, string Name);
+
+public class CreateUserCommandValidator : AbstractValidator<CreateUserCommand>
+{
+    public CreateUserCommandValidator()
+    {
+        RuleFor(x => x.Email)
+            .NotEmpty().WithMessage("Email is required")
+            .EmailAddress().WithMessage("Email must be valid");
+
+        RuleFor(x => x.Name)
+            .NotEmpty().WithMessage("Name is required")
+            .MaximumLength(100).WithMessage("Name must not exceed 100 characters");
+    }
+}
+
+public class CreateUserCommandHandler
+{
+    private readonly IUserRepository _userRepository;
+    private readonly IValidator<CreateUserCommand> _validator;
+
+    public CreateUserCommandHandler(
+        IUserRepository userRepository,
+        IValidator<CreateUserCommand> validator)
+    {
+        _userRepository = userRepository;
+        _validator = validator;
+    }
+
+    public async Task<UserResponseDto> HandleAsync(
+        CreateUserCommand command, 
+        CancellationToken cancellationToken = default)
+    {
+        // 1. Validate command
+        await _validator.ValidateAndThrowAsync(command, cancellationToken);
+
+        // 2. Validate business rules
+        await ValidateUserDoesNotExistAsync(command.Email, cancellationToken);
+
+        // 3. Create domain entity
+        var user = UserEntity.Create(command.Email, command.Name);
+
+        // 4. Persist entity
+        var savedUser = await _userRepository.SaveAsync(user, cancellationToken);
+
+        // 5. Return response DTO
+        return UserResponseDto.FromEntity(savedUser);
+    }
+
+    private async Task ValidateUserDoesNotExistAsync(string email, CancellationToken cancellationToken)
+    {
+        var emailVO = EmailValueObject.Create(email);
+        var existingUser = await _userRepository.FindByEmailAsync(emailVO, cancellationToken);
+        if (existingUser != null)
+            throw new UserAlreadyExistsException(email);
+    }
+}
+```
+
+### Query Structure
+```csharp
+public record GetUserByIdQuery(Guid Id);
+
+public class GetUserByIdQueryHandler
+{
+    private readonly IUserRepository _userRepository;
+
+    public GetUserByIdQueryHandler(IUserRepository userRepository)
+    {
+        _userRepository = userRepository;
+    }
+
+    public async Task<UserResponseDto?> HandleAsync(
+        GetUserByIdQuery query, 
+        CancellationToken cancellationToken = default)
+    {
+        var user = await _userRepository.FindByIdAsync(query.Id, cancellationToken);
+        return user != null ? UserResponseDto.FromEntity(user) : null;
+    }
+}
+```
+
+### DTO Structure
+```csharp
+public record UserResponseDto
+{
+    public Guid Id { get; init; }
+    public string Email { get; init; }
+    public string Name { get; init; }
+
+    public static UserResponseDto FromEntity(UserEntity user)
+    {
+        return new UserResponseDto
+        {
+            Id = user.Id,
+            Email = user.Email.Value,
+            Name = user.Name.Value
+        };
+    }
+}
+
+```
+
+## Minimal API Standards
+
+### Endpoint Structure
+```csharp
+// Program.cs or separate endpoint configuration
+public static class UserEndpoints
+{
+    public static void MapUserEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/api/users")
+            .WithTags("Users")
+            .WithOpenApi();
+
+        group.MapPost("/", CreateUser)
+            .WithName("CreateUser")
+            .WithSummary("Create a new user")
+            .Produces<UserResponseDto>(StatusCodes.Status201Created)
+            .ProducesValidationProblem();
+
+        group.MapGet("/{id:guid}", GetUserById)
+            .WithName("GetUserById")
+            .WithSummary("Get user by ID")
+            .Produces<UserResponseDto>()
+            .Produces(StatusCodes.Status404NotFound);
+    }
+
+    private static async Task<IResult> CreateUser(
+        CreateUserCommand command,
+        CreateUserCommandHandler handler,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            var result = await handler.HandleAsync(command, cancellationToken);
+            return Results.Created($"/api/users/{result.Id}", result);
+        }
+        catch (ValidationException ex)
+        {
+            return Results.ValidationProblem(ex.Errors.ToDictionary(
+                e => e.PropertyName,
+                e => new[] { e.ErrorMessage }));
+        }
+        catch (UserAlreadyExistsException ex)
+        {
+            return Results.Conflict(new { message = ex.Message });
+        }
+    }
+
+    private static async Task<IResult> GetUserById(
+        Guid id,
+        GetUserByIdQueryHandler handler,
+        CancellationToken cancellationToken)
+    {
+        var result = await handler.HandleAsync(new GetUserByIdQuery(id), cancellationToken);
+        return result != null ? Results.Ok(result) : Results.NotFound();
+    }
+}
+```
+
+## Testing Standards
+
+### Testing Strategy
+- **Unit Tests**: Domain entities, value objects, command/query handlers (isolated logic)
+- **Integration Tests**: Repository implementations, database operations with EF Core InMemory or Test Containers
+- **TDD Approach**: Write tests before or alongside implementation
+- **High Coverage**: Aim for >80% code coverage
+
+### Test Structure (xUnit)
+```csharp
+public class CreateUserCommandHandlerTests
+{
+    private readonly Mock<IUserRepository> _userRepositoryMock;
+    private readonly Mock<IValidator<CreateUserCommand>> _validatorMock;
+    private readonly CreateUserCommandHandler _handler;
+
+    public CreateUserCommandHandlerTests()
+    {
+        _userRepositoryMock = new Mock<IUserRepository>();
+        _validatorMock = new Mock<IValidator<CreateUserCommand>>();
+        _handler = new CreateUserCommandHandler(
+            _userRepositoryMock.Object,
+            _validatorMock.Object);
+    }
+
+    [Fact]
+    public async Task HandleAsync_WithValidCommand_ShouldCreateUser()
+    {
+        // Arrange
+        var command = new CreateUserCommand("test@example.com", "John Doe");
+        _validatorMock
+            .Setup(v => v.ValidateAndThrowAsync(command, It.IsAny<CancellationToken>()))
+            .Returns(Task.CompletedTask);
+        _userRepositoryMock
+            .Setup(r => r.FindByEmailAsync(It.IsAny<EmailValueObject>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync((UserEntity?)null);
+        _userRepositoryMock
+            .Setup(r => r.SaveAsync(It.IsAny<UserEntity>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync((UserEntity u, CancellationToken _) => u);
+
+        // Act
+        var result = await _handler.HandleAsync(command, CancellationToken.None);
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.Equal(command.Email, result.Email);
+        Assert.Equal(command.Name, result.Name);
+        _userRepositoryMock.Verify(r => r.SaveAsync(It.IsAny<UserEntity>(), It.IsAny<CancellationToken>()), Times.Once);
+    }
+
+    [Fact]
+    public async Task HandleAsync_WithExistingUser_ShouldThrowException()
+    {
+        // Arrange
+        var command = new CreateUserCommand("test@example.com", "John Doe");
+        var existingUser = UserEntity.Create("test@example.com", "Existing User");
+        _validatorMock
+            .Setup(v => v.ValidateAndThrowAsync(command, It.IsAny<CancellationToken>()))
+            .Returns(Task.CompletedTask);
+        _userRepositoryMock
+            .Setup(r => r.FindByEmailAsync(It.IsAny<EmailValueObject>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(existingUser);
+
+        // Act & Assert
+        await Assert.ThrowsAsync<UserAlreadyExistsException>(() => 
+            _handler.HandleAsync(command, CancellationToken.None));
+    }
+}
+```
+
+### Integration Test with EF Core InMemory
+```csharp
+public class UserRepositoryIntegrationTests : IDisposable
+{
+    private readonly ApplicationDbContext _context;
+    private readonly UserRepository _repository;
+
+    public UserRepositoryIntegrationTests()
+    {
+        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
+            .UseInMemoryDatabase(databaseName: Guid.NewGuid().ToString())
+            .Options;
+
+        _context = new ApplicationDbContext(options);
+        _repository = new UserRepository(_context);
+    }
+
+    [Fact]
+    public async Task SaveAsync_ShouldPersistUser()
+    {
+        // Arrange
+        var user = UserEntity.Create("test@example.com", "John Doe");
+
+        // Act
+        var savedUser = await _repository.SaveAsync(user);
+
+        // Assert
+        var retrievedUser = await _repository.FindByIdAsync(savedUser.Id);
+        Assert.NotNull(retrievedUser);
+        Assert.Equal(user.Email.Value, retrievedUser.Email.Value);
+    }
+
+    public void Dispose()
+    {
+        _context.Database.EnsureDeleted();
+        _context.Dispose();
+    }
+}
+```
+
+## EF Core Configuration Standards
+
+### DbContext Configuration
+```csharp
+public class ApplicationDbContext : DbContext
+{
+    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) 
+        : base(options)
+    {
+    }
+
+    public DbSet<UserEntity> Users { get; set; }
+    public DbSet<QuoteEntity> Quotes { get; set; }
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+
+        // Apply all configurations from assembly
+        modelBuilder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
+    }
+}
+```
+
+### Entity Configuration
+```csharp
+public class UserEntityConfiguration : IEntityTypeConfiguration<UserEntity>
+{
+    public void Configure(EntityTypeBuilder<UserEntity> builder)
+    {
+        builder.ToTable("Users");
+        
+        builder.HasKey(u => u.Id);
+        
+        builder.Property(u => u.Id)
+            .HasColumnType("uuid")
+            .IsRequired();
+
+        // Configure Value Object as owned entity
+        builder.OwnsOne(u => u.Email, email =>
+        {
+            email.Property(e => e.Value)
+                .HasColumnName("Email")
+                .HasMaxLength(256)
+                .IsRequired();
+        });
+
+        builder.OwnsOne(u => u.Name, name =>
+        {
+            name.Property(n => n.Value)
+                .HasColumnName("Name")
+                .HasMaxLength(100)
+                .IsRequired();
+        });
+
+        // Ignore domain events (not persisted)
+        builder.Ignore(u => u.DomainEvents);
+    }
+}
+```
+
+## Security Standards
+
+### Authentication & Authorization
+- **JWT Tokens**: Proper expiration and refresh token handling
+- **RBAC**: Role-based access control
+- **Validation**: Input validation on all endpoints (FluentValidation)
+- **Rate Limiting**: Throttle public endpoints to prevent abuse
+- **Environment**: HTTPS only in production, secrets in env variables
+
+### Data Protection
+- Encrypt sensitive data at rest and in transit
+- Never commit secrets to repository
+- Implement audit logging for critical operations
+- OWASP Top 10 compliance
+- Regular dependency security audits with `dotnet list package --vulnerable`
+
+## Performance Standards
+
+### Database Optimization
+- Proper indexing on frequently queried fields
+- Connection pooling via EF Core 10
+- Pagination for large datasets (Skip/Take or cursor-based)
+- Avoid N+1 queries with `.Include()` and `.ThenInclude()`
+- Query monitoring and slow query logging
+- Use `AsNoTracking()` for read-only queries
+
+### Caching Strategy
+- **Distributed Cache**: Redis for session data and frequently accessed data
+- **Memory Cache**: In-memory caching for configuration
+- **TTL Strategy**: Appropriate time-to-live for different data types
+- **Invalidation**: Event-driven cache invalidation
+
+## Error Handling
+
+### Exception Hierarchy
+- Domain exceptions for business rule violations
+- Application exceptions for use case errors
+- Infrastructure exceptions for external service failures
+- Global exception middleware for API responses
+
+### Error Response Format (Problem Details RFC 7807)
+```csharp
+public record ProblemDetailsResponse
+{
+    public int Status { get; init; }
+    public string Title { get; init; }
+    public string Detail { get; init; }
+    public string Instance { get; init; }
+    public DateTimeOffset Timestamp { get; init; }
+    public Dictionary<string, string[]>? Errors { get; init; }
+}
+
+// Example response
+{
+  "status": 400,
+  "title": "Validation Error",
+  "detail": "One or more validation errors occurred",
+  "instance": "/api/users",
+  "timestamp": "2025-11-26T10:30:00Z",
+  "errors": {
+    "Email": ["Email is required", "Email must be valid"],
+    "Name": ["Name is required"]
+  }
+}
+```
+
+### Global Exception Middleware
+```csharp
+public class ExceptionHandlingMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<ExceptionHandlingMiddleware> _logger;
+
+    public ExceptionHandlingMiddleware(
+        RequestDelegate next,
+        ILogger<ExceptionHandlingMiddleware> logger)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await _next(context);
+        }
+        catch (ValidationException ex)
+        {
+            await HandleValidationExceptionAsync(context, ex);
+        }
+        catch (DomainException ex)
+        {
+            await HandleDomainExceptionAsync(context, ex);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Unhandled exception occurred");
+            await HandleUnhandledExceptionAsync(context, ex);
+        }
+    }
+
+    private static Task HandleValidationExceptionAsync(HttpContext context, ValidationException exception)
+    {
+        context.Response.StatusCode = StatusCodes.Status400BadRequest;
+        context.Response.ContentType = "application/problem+json";
+
+        var problemDetails = new ProblemDetailsResponse
+        {
+            Status = StatusCodes.Status400BadRequest,
+            Title = "Validation Error",
+            Detail = "One or more validation errors occurred",
+            Instance = context.Request.Path,
+            Timestamp = DateTimeOffset.UtcNow,
+            Errors = exception.Errors.GroupBy(e => e.PropertyName)
+                .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray())
+        };
+
+        return context.Response.WriteAsJsonAsync(problemDetails);
+    }
+}
+```
+
+## Security Standards
+
+### Authentication & Authorization
+- **JWT Tokens**: Proper expiration and refresh token handling
+- **RBAC**: Role-based access control with Authorization Policies
+- **Validation**: Input validation on all endpoints (FluentValidation)
+- **Rate Limiting**: ASP.NET Core Rate Limiting middleware
+- **Environment**: HTTPS only in production, secrets in Azure Key Vault or User Secrets
+
+### Data Protection
+- Encrypt sensitive data at rest and in transit
+- Never commit secrets to repository
+- Implement audit logging for critical operations
+- OWASP Top 10 compliance
+- Regular dependency security audits with `dotnet list package --vulnerable`
+
+## Performance Standards
+
+### Database Optimization
+- Proper indexing on frequently queried fields
+- Connection pooling via EF Core (configured in connection string)
+- Pagination for large datasets (Skip/Take or Keyset pagination)
+- Avoid N+1 queries with `.Include()` and `.ThenInclude()`
+- Query monitoring and slow query logging
+- Use `AsNoTracking()` for read-only queries
+
+### Caching Strategy
+- **Distributed Cache**: Redis or SQL Server for distributed scenarios
+- **Memory Cache**: `IMemoryCache` for single-instance caching
+- **TTL Strategy**: Appropriate time-to-live for different data types
+- **Invalidation**: Event-driven cache invalidation
+- **Response Caching**: Use `[ResponseCache]` attribute for GET endpoints
+
+## Additional Standards
+
+### Logging
+- Use `ILogger<T>` for structured logging
+- Log levels: Trace, Debug, Information, Warning, Error, Critical
+- Include correlation IDs for request tracing
+- Never log sensitive information (passwords, tokens, PII)
+
+### API Versioning
+- Use URL versioning: `/api/v1/users`
+- Support multiple versions simultaneously during migration
+- Deprecation notices in response headers
+
+### Health Checks
+- Implement `/health` endpoint for liveness
+- Implement `/health/ready` for readiness checks
+- Include database, cache, and external service checks