Node Clean Architecture (Express)

This repository demonstrates a clean and maintainable architecture for building Node.js APIs using Express. The goal is to show how to structure an application so that business logic is independent of the web framework and easy to test, extend, and reason about.

This is not a full-featured API. It is a focused example of how to organise code correctly in a real-world Node.js application.

---

Goals

• Keep Express as an infrastructure concern
• Separate HTTP, business logic, and data access
• Make core logic framework-agnostic
• Improve readability, testability, and maintainability
• Avoid over-engineering or framework magic

---

Architecture Overview

The application is split into clear layers:

• Routes Define HTTP endpoints and map them to controllers.

• Controllers Handle HTTP-specific concerns such as request and response objects.

• Services Contain business logic and application rules.

• Repositories Handle data access (in-memory for this example).

• Models Represent domain entities.

Each layer has a single responsibility and depends only on the layer below it.

---

Project Structure

src/
├── app.js
├── server.js
│
├── routes/
│   └── userRoutes.js
│
├── controllers/
│   └── userController.js
│
├── services/
│   └── userService.js
│
├── repositories/
│   └── userRepository.js
│
├── models/
│   └── user.js
│
├── middlewares/
│   └── asyncHandler.js
│
└── utils/
    └── response.js

---

Why This Structure Works

• Express can be replaced without touching business logic
• Services can be tested independently of HTTP
• Data storage can be swapped without affecting controllers
• The codebase scales naturally as features grow

This pattern is commonly used in production systems to reduce technical debt and improve long-term maintainability.

---

Getting Started

Install dependencies

npm install

Run the server

npm start

The server runs on:

http://localhost:3000

---

Available Endpoints

Get all users

GET /users

Create a user

POST /users

Request body:

{
  "name": "John Doe",
  "email": "john@example.com"
}

---

Notes

• Data is stored in memory for simplicity
• No database is required
• Error handling and validation are intentionally minimal to keep the focus on architecture

---

Who This Is For

• Developers learning backend architecture
• Engineers transitioning from small apps to scalable systems
• Anyone who wants a clean mental model for Node.js APIs

---

License

MIT