adastra_api/docs/decisions/0001-framework-expressjs.md

ADR 0001: Backend Framework — Express.js

Date: 2026-04-26 Status: Accepted

Context

The backend serves a JSON REST API consumed by the Angular frontend. The requirements are straightforward: HTTP routing, middleware chaining, JSON body parsing, JWT authentication, and database access. No server-side rendering, no real-time features, no heavy framework conventions are needed.

Decision

Use Express.js as the HTTP framework. The application is structured around:

• src/routes/api/<domain>/ — route definitions by functional domain
• src/controllers/ — request/response handling
• src/services/ — business logic
• src/middlewares/ — cross-cutting concerns (auth, error handling, async wrapper)
• createApp.js — application factory (separates app creation from server startup, enabling testability)

Consequences

• Positive: Minimal abstraction. Full control over middleware order and request lifecycle.
• Positive: Large ecosystem. Well-understood by the team.
• Negative: No convention over configuration — project structure is manually maintained.
• Negative: Async error handling requires explicit wrapping (asyncHandler middleware) since Express 4 does not catch promise rejections natively. Express 5 (not yet used) handles this automatically.