# ADR 0004: Route Organisation by Functional Domain

**Date:** 2026-04-26
**Status:** Accepted

## Context

The API covers four independent functional domains (skydive, cms, ecommerce, herowars), each with distinct models, business logic, and frontend consumers. A flat route structure would make it difficult to reason about domain boundaries and onboard new contributors.

## Decision

Routes are grouped under `src/routes/api/<domain>/` with a barrel index (`src/routes/api/index.js`). Each domain owns its routes, controllers, services, and models independently. The domain prefix is reflected in the API path (e.g. `/api/skydive/jumps`, `/api/cms/articles`).

This structure mirrors the frontend's domain organisation (see frontend ADR 0011), making the full-stack data flow traceable: a frontend service under `core/services/skydive/` calls `/skydive/` routes, which map to `src/routes/api/skydive/`.

Legacy `v1/`, `v2/`, `v3/` directories exist alongside the active routes as backup snapshots from earlier iterations. They are slated for removal once their contents are confirmed no longer needed (see ADR 0007).

## Consequences

- **Positive:** Domain boundaries are explicit and enforced by directory structure.
- **Positive:** Consistent mapping between frontend service paths and backend routes simplifies debugging.
- **Negative:** Cross-domain features (shared auth middleware, user model) live in `src/middlewares/` and `src/database/models/` respectively, outside any domain folder.