gridpilot.gg/docs/architecture/shared/REPOSITORY_STRUCTURE.md

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)

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.

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.

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/website/WEBSITE_FILE_STRUCTURE.md

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.