gridpilot.gg/docs/architecture/api/API_DATA_FLOW.md

API Data Flow (Strict)

This document defines the apps/api data flow and responsibilities.

API scope:

• apps/api/**

1) API role

The API is a delivery application.

Responsibilities:

• HTTP transport boundary
• authentication and authorization enforcement
• request validation (transport shape)
• mapping between HTTP DTOs and Core inputs
• calling Core use cases
• mapping Core results into HTTP responses

2) API data types (strict)

2.1 Request DTO

Definition: HTTP request contract shape.

Rules:

• lives in the API layer
• validated at the API boundary
• never enters Core unchanged

2.2 Response DTO

Definition: HTTP response contract shape.

Rules:

• lives in the API layer
• never contains domain objects

2.3 API Presenter

Definition: mapping logic from Core results to HTTP response DTOs.

Rules:

• pure transformation
• no business rules
• may hold state per request

3) Canonical flow

HTTP Request
  ↓
Guards (auth, authorization, feature availability)
  ↓
Controller (transport-only)
  ↓
Mapping: Request DTO → Core input
  ↓
Core Use Case
  ↓
Mapping: Core result → Response DTO (Presenter)
  ↓
HTTP Response

4) Non-negotiable rules

1. Controllers contain no business rules.
2. Controllers do not construct domain objects.
3. Core results never leave the API without mapping.

See authorization model: docs/architecture/api/AUTHORIZATION.md.