julien
a9ef4cf629
Rewrites all 7 backend ADRs from a custom structure to the MADR 2.1.2 template required by the VS Code ADR Manager extension: bullet metadata (Status/Date), standardised section headings, "Chosen option: X, because Y" wording, and explicit Pros/Cons blocks per option.
47 lines
2.1 KiB
Markdown
47 lines
2.1 KiB
Markdown
# 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)
|