# Organise routes by functional domain

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

## Context and Problem Statement

The API covers four independent functional domains (skydive, cms, ecommerce, herowars), each with distinct models, business logic, and frontend consumers. How should routes be organised to reflect these boundaries?

## Considered Options

* Domain-based organisation (`src/routes/api/<domain>/`)
* Flat structure (all routes at one level)

## Decision Outcome

Chosen option: "Domain-based organisation", because it makes domain boundaries explicit and mirrors the frontend's service structure, making the full-stack data flow traceable.

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

### Positive Consequences

* Domain boundaries are explicit and enforced by directory structure.
* Consistent mapping between frontend service paths and backend routes simplifies debugging — a frontend service under `core/services/skydive/` maps to `src/routes/api/skydive/`.

### Negative Consequences

* Cross-domain features (shared auth middleware, user model) live in `src/middlewares/` and `src/database/models/` respectively, outside any domain folder.

## Pros and Cons of the Options

### Domain-based organisation

* Good, because each domain is self-contained and independently navigable.
* Good, because symmetric with the frontend service structure.
* Bad, because shared concerns need a neutral layer outside domain folders.

### Flat structure

* Good, because simpler for very small APIs.
* Bad, because domain boundaries become invisible as the API grows.

## Links

* Legacy `v1/`, `v2/`, `v3/` directories exist alongside `api/` as backup snapshots from earlier iterations — see [ADR 0007](0007-legacy-routes-removal.md) for their planned removal.
* Related to frontend [ADR 0011](../../adastra_app/docs/decisions/0011-feature-domain-organisation.md)