Structuring Express Apps with Layered Architecture

Why it exists

Express.js is unopinionated, which is flexible but can lead to chaos. Without a clear structure, projects become hard to maintain, test, and scale as code gets tangled. A layered architecture provides a standard blueprint to enforce separation of concerns from the start, preventing future rewrites.

The mental model

Imagine your application as a three-story building with strict rules. The top floor is the Web Layer, handling all incoming and outgoing HTTP traffic. The middle floor is the Service Layer, where all the business rules and logic live. The basement is the Data Access Layer, which is the only part of the building allowed to talk to the database. Each layer should only communicate with the layer directly adjacent to it.

How it works

This architecture organizes your code into three distinct modules. First, the Web Layer contains your routes, controllers, and middleware; it receives requests, validates input, and sends responses. Second, the Service Layer is called by controllers and contains the core business logic, orchestrating tasks without knowing about HTTP. Third, the Data Access Layer is called by services and handles all database read/write operations, often using an ORM like Mongoose or Sequelize.

When to use it

Use a layered architecture for any Express.js REST API that you expect to grow beyond a simple prototype. It is the standard for building robust, maintainable, and scalable applications. It also simplifies unit testing, as you can test business logic (services) without starting an HTTP server or connecting to a live database.

When not to use it

For a quick, throwaway script or a tiny microservice with a single endpoint, a full layered structure might feel like overkill. However, the discipline it enforces often pays off as soon as a project's requirements expand unexpectedly.

One canonical example

A common mistake is putting all logic into a single server.js. A better approach separates the HTTP server from the application logic. Create a server.js that only imports the app and starts the listener (app.listen(port)). Then, in a separate app.js file, define your Express app, middleware, and routes. This separation allows you to import and test the app object in your unit tests without actually starting a live server.