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

docs/architecture/api/API_FILE_STRUCTURE.md

@@ -0,0 +1,38 @@
+# API File Structure (Strict)
+
+This document defines the canonical **physical** structure for `apps/api/**`.
+
+It describes where code lives, not the full behavioral rules.
+
+## 1) API is feature-based
+
+The API is organized by feature modules.
+
+```text
+apps/api/
+  src/
+    domain/
+    shared/
+```
+
+Within feature modules:
+
+```text
+apps/api/src/domain/<feature>/
+  <Feature>Controller.ts
+  <Feature>Service.ts
+  <Feature>Module.ts
+  dto/
+  presenters/
+```
+
+## 2) What belongs where (strict)
+
+- Controllers: HTTP boundary only
+- DTOs: HTTP contracts only
+- Presenters: map Core results  response DTOs
+
+API flow rules:
+
+- [`docs/architecture/api/API_DATA_FLOW.md`](docs/architecture/api/API_DATA_FLOW.md:1)
+

docs/architecture/api/AUTHORIZATION.md

@@ -12,7 +12,7 @@ It complements (but does not replace) feature availability:
 - Authorization answers: “Is this actor allowed to do it?”
 
 Related:
-- Feature gating concept: docs/architecture/FEATURE_AVAILABILITY.md
+- Feature gating concept: [`docs/architecture/shared/FEATURE_AVAILABILITY.md`](docs/architecture/shared/FEATURE_AVAILABILITY.md:1)
 
 
 ---
@@ -154,7 +154,7 @@ Return **404** when:
 Use this sparingly and intentionally.
 
 ### 6.3 Feature availability interaction
-Feature availability failures (disabled/hidden/coming soon) should behave as “not found” for public callers, while maintenance mode should return 503. See docs/architecture/FEATURE_AVAILABILITY.md.
+Feature availability failures (disabled/hidden/coming soon) should behave as “not found” for public callers, while maintenance mode should return 503. See [`docs/architecture/shared/FEATURE_AVAILABILITY.md`](docs/architecture/shared/FEATURE_AVAILABILITY.md:1).
 
 
 ---
@@ -253,4 +253,4 @@ Rules:
 - A super-admin UI can manage:
   - global roles (owner/admin)
   - scoped roles (league_owner/admin/steward, sponsor_owner/admin, team_owner/admin)
-- Feature availability remains a separate control plane (maintenance mode, coming soon, kill switches), documented in docs/architecture/FEATURE_AVAILABILITY.md.
+- Feature availability remains a separate control plane (maintenance mode, coming soon, kill switches), documented in [`docs/architecture/shared/FEATURE_AVAILABILITY.md`](docs/architecture/shared/FEATURE_AVAILABILITY.md:1).

docs/architecture/api/AUTH_FLOW.md

@@ -0,0 +1,47 @@
+# Authentication and Authorization Flow (API)
+
+This document defines how authentication and authorization are enforced in the API.
+
+Shared contract:
+
+- [`docs/architecture/shared/AUTH_CONTRACT.md`](docs/architecture/shared/AUTH_CONTRACT.md:1)
+
+## 1) Enforcement location (strict)
+
+All enforcement happens in the API.
+
+The API must:
+
+- authenticate the actor from the session
+- authorize the actor for the requested capability
+- deny requests deterministically with appropriate HTTP status
+
+## 2) Canonical request flow
+
+```text
+HTTP Request
+  ↓
+Authentication (resolve actor)
+  ↓
+Authorization (roles, permissions, scope)
+  ↓
+Controller (transport-only)
+  ↓
+Core Use Case
+  ↓
+Presenter mapping
+  ↓
+HTTP Response
+```
+
+## 3) Non-negotiable rules
+
+1. Deny by default unless explicitly public.
+2. The actor identity is derived from the session.
+3. Controllers do not contain business rules.
+
+Related:
+
+- Authorization model: [`docs/architecture/api/AUTHORIZATION.md`](docs/architecture/api/AUTHORIZATION.md:1)
+- Guards definition: [`docs/architecture/api/GUARDS.md`](docs/architecture/api/GUARDS.md:1)
+

docs/architecture/api/GUARDS.md

@@ -0,0 +1,47 @@
+# Guards (API Enforcement)
+
+This document defines **Guards** as API enforcement mechanisms.
+
+Shared contract: [`docs/architecture/shared/BLOCKERS_AND_GUARDS.md`](docs/architecture/shared/BLOCKERS_AND_GUARDS.md:1)
+
+## 1) Definition
+
+A Guard is an API mechanism that enforces access or execution rules.
+
+If a Guard denies execution, the request does not reach application logic.
+
+## 2) Responsibilities
+
+Guards MAY:
+
+- block requests entirely
+- return HTTP errors (401, 403, 429)
+- enforce authentication and authorization
+- enforce rate limits
+- enforce feature availability
+- protect against abuse and attacks
+
+Guards MUST:
+
+- be deterministic
+- be authoritative
+- be security-relevant
+
+## 3) Restrictions
+
+Guards MUST NOT:
+
+- depend on website/client state
+- contain UI logic
+- attempt to improve UX
+- assume the client behaved correctly
+
+## 4) Common Guards
+
+- AuthGuard
+- RolesGuard
+- PermissionsGuard
+- Throttler/RateLimit guards
+- CSRF guards
+- Feature availability guards
+

docs/architecture/api/USE_CASE_WIRING.md

@@ -0,0 +1,38 @@
+# Use Case Wiring (API) (Strict)
+
+This document defines how the API wires HTTP requests to Core Use Cases.
+
+Core contract:
+
+- [`docs/architecture/core/USECASES.md`](docs/architecture/core/USECASES.md:1)
+
+## 1) Non-negotiable rules
+
+1. Controllers are transport boundaries.
+2. Controllers validate request DTOs.
+3. Controllers map request DTOs to Core inputs.
+4. Controllers execute Core Use Cases.
+5. Controllers map Core results to response DTOs.
+
+## 2) Presenter meaning in the API
+
+In the API, a Presenter is an output adapter that maps Core results to HTTP response DTOs.
+
+Rule:
+
+- API presenters are request-scoped. They must not be shared across concurrent requests.
+
+## 3) Canonical flow
+
+```text
+HTTP Request DTO
+  ↓
+Controller mapping
+  ↓
+Core Use Case
+  ↓
+Presenter mapping
+  ↓
+HTTP Response DTO
+```
+