# Use Express.js as the HTTP framework

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

## Context and Problem Statement

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

## Considered Options

* Express.js
* Fastify
* NestJS

## Decision Outcome

Chosen option: "Express.js", because it provides full control over middleware order and request lifecycle with minimal abstraction, and is well understood without requiring conventions to be learned.

The application is structured around: `src/routes/api/<domain>/` (route definitions), `src/controllers/` (request/response handling), `src/services/` (business logic), `src/middlewares/` (cross-cutting concerns), and `createApp.js` (application factory separating app creation from server startup for testability).

### Positive Consequences

* Minimal abstraction — full control over middleware order and request lifecycle.
* Large ecosystem with well-understood patterns.

### Negative Consequences

* No convention over configuration — project structure is manually maintained.
* 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.

## Pros and Cons of the Options

### Express.js

* Good, because minimal and flexible — no forced conventions.
* Good, because widely known ecosystem.
* Bad, because no built-in async error handling in v4.

### Fastify

* Good, because faster than Express, built-in schema validation.
* Bad, because less familiar; migration cost not justified for current scale.

### NestJS

* Good, because strong conventions, TypeScript-first, built-in dependency injection.
* Bad, because heavyweight — conventions and abstractions are not needed for a straightforward REST API.
* Bad, because would require migrating the entire codebase.