copilot-instructions backend.instructions.md

Clean Architecture

• Pure Domain rules
• Application orchestrates
• Infrastructure adapts
• API exposes
• Simplicity first
• Avoid over-engineering

// Domain → OrderService validates business rules
// Application → OrderHandler orchestrates
// Infrastructure → OrderRepository persists
// API → OrdersController exposes endpoint

CQRS

• Separate read/write
• Cohesive handlers
• Idempotency when needed
• Apply only when complexity justifies

// Command → CreateOrderHandler
// Query → GetOrderByIdHandler

Events

• Domain/integration events + Outbox
• Idempotent consumers
• DLQ for queues
• Avoid unnecessary event sourcing

// OrderCreatedEvent stored in Outbox
// Consumer with retry + DLQ

Contracts/Errors

• Versioned REST
• Consistent paging/filters
• RFC 7807 (ProblemDetails) with correlationId

{
  "type": "about:blank",
  "title": "Invalid request",
  "status": 400,
  "detail": "name is required",
  "instance": "/v1/orders",
  "extensions": { "correlationId": "<uuid>" }
}

Resilience

• HTTP with timeout, retry (jitter), circuit breaker, bulkhead
• Always CancellationToken (or equivalent)
• Implement gradually as needed

// HttpClientFactory with Polly AddTransientHttpErrorPolicy → WaitAndRetryAsync with jitter

Data

• Transactions per use case
• Repositories via interfaces
• Projections
• Indexes/constraints
• Cache with clear invalidation

// IOrderRepository.SaveAsync() with TransactionScope
// Unique index on Email
// Redis cache with explicit expiration

Security

• Input validation
• JWT/OIDC
• Policies/roles
• Minimal CORS
• Secrets in secure store

// [Authorize(Policy="Admin")] on Controller
// Secret loaded from AWS Secrets Manager or Azure Key Vault

Observability

• OpenTelemetry (traces/metrics/logs)
• Structured logs
• Health checks
• Readiness/liveness probes

// ActivitySource for OrderService
// HealthCheck endpoints "/health/ready" and "/health/live"