docs

docs/architecture/shared/REPOSITORY_STRUCTURE.md

@@ -0,0 +1,56 @@
+# Repository Structure (Shared Contract)
+
+This document defines the **physical repository structure**.
+
+It describes **where** code lives, not what responsibilities are.
+
+## 1) Top-level layout (strict)
+
+```text
+core/         business logic (framework-free)
+adapters/     reusable infrastructure implementations
+apps/         delivery applications (API, website)
+docs/         documentation
+tests/        cross-app tests
+```
+
+## 2) Meaning of each top-level folder
+
+### 2.1 `core/`
+
+The Core contains domain and application logic.
+
+See [`docs/architecture/core/CORE_FILE_STRUCTURE.md`](docs/architecture/core/CORE_FILE_STRUCTURE.md:1).
+
+### 2.2 `adapters/`
+
+Adapters are **reusable outer-layer implementations**.
+
+Rules:
+
+- adapters implement Core ports
+- adapters contain technical details (DB, external systems)
+- adapters do not define HTTP routes
+
+See [`docs/architecture/shared/ADAPTERS.md`](docs/architecture/shared/ADAPTERS.md:1).
+
+### 2.3 `apps/`
+
+Apps are **delivery mechanisms**.
+
+This repo has (at minimum):
+
+- `apps/api` (HTTP API)
+- `apps/website` (Next.js website)
+
+See:
+
+- [`docs/architecture/api/API_FILE_STRUCTURE.md`](docs/architecture/api/API_FILE_STRUCTURE.md:1)
+- [`docs/architecture/website/WEBSITE_FILE_STRUCTURE.md`](docs/architecture/website/WEBSITE_FILE_STRUCTURE.md:1)
+
+## 3) Non-negotiable rules
+
+1. Business truth lives in `core/`.
+2. `apps/*` are delivery apps; they translate and enforce.
+3. `adapters/*` implement ports and contain technical details.
+