Backend Guide

The backend is optional and designed to be added without disrupting frontend-first workflows.

Architecture Boundaries

The backend follows clean architecture:

  • API layer: HTTP transport, middleware, endpoint wiring
  • Core layer: domain entities, contracts, and business rules
  • Infrastructure layer: database and external service implementations
  • Test layer: behavior verification

This separation keeps domain logic portable and easier to test.

Request Lifecycle

  1. Request arrives at API endpoint
  2. Middleware applies shared concerns (errors, telemetry, policy)
  3. Domain logic runs through core contracts
  4. Infrastructure persists or fetches data
  5. Response is returned in a consistent envelope

Error and Health Conventions

  • Domain exceptions map to meaningful HTTP status codes
  • Unexpected exceptions are logged and returned as safe responses
  • Readiness and liveness endpoints are available for orchestration

Local Development

Use the app host for full-stack local orchestration (database, API, frontend, and dashboard).
Use backend-only execution for focused API iteration.

Build and Test

cd backend
dotnet build
dotnet test

Adding New Features

Keep new features aligned to layer boundaries:

  1. Define domain models/contracts in core
  2. Implement persistence/integration in infrastructure
  3. Expose behavior through API endpoints
  4. Add tests for behavior and error cases