docs

docs/architecture/api/API_DATA_FLOW.md

@@ -0,0 +1,78 @@
+# 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
+
+```text
+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`](docs/architecture/api/AUTHORIZATION.md:1).
+