adastra_api/docs/decisions/0004-route-organisation-by-domain.md

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.