# 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).