docs

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