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