Clean Architecture with Node.js & TypeScript

A production-ready REST API built with Node.js, TypeScript, and Clean Architecture principles. This project demonstrates how to create a maintainable, scalable, and testable backend application with proper separation of concerns.

🎯 Key Features

• ✅ Clean Architecture - Clear separation of concerns across 4 layers
• ✅ Database-Agnostic - Easy to switch from MongoDB to PostgreSQL, MySQL, etc.
• ✅ TypeScript - Full type safety with strict mode enabled
• ✅ Repository Pattern - Abstracted data access layer
• ✅ Dependency Injection - Manual DI using factory pattern
• ✅ Validation - Input validation using Joi schemas
• ✅ Error Handling - Centralized error handling middleware
• ✅ Logging - Structured logging with Winston
• ✅ Security - Helmet, CORS, and security best practices
• ✅ Production-Ready - Optimized for deployment

📋 Table of Contents

• Architecture
• Project Structure
• Getting Started
• API Endpoints
• Environment Variables
• Development
• Production Build
• Testing the API
• Database-Agnostic Design
• Contributing
• License

🏗️ Architecture

This project follows Clean Architecture principles with 4 distinct layers:

┌─────────────────────────────────────────────────┐
│          Interfaces Layer (HTTP)                │
│   Controllers → Routes → Middleware             │
└──────────────────┬────────────────────────────┬─┘
                   │                            │
                   ▼                            │
┌─────────────────────────────────────────────  │
│      Application Layer (Business Logic)       │
│             Services                           │
└──────────────────┬────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│         Domain Layer (Core Business)        │
│   Entities → Repository Interfaces          │
└─────────────────────────────────────────────┘
                   ▲
                   │
┌─────────────────────────────────────────────┐
│     Infrastructure Layer (External I/O)     │
│   Database → Email → File Storage           │
└─────────────────────────────────────────────┘

Layer Responsibilities

1. Domain Layer (Core)

• Contains business entities and repository interfaces
• No dependencies on other layers or external frameworks
• Pure TypeScript interfaces defining the domain model

2. Application Layer

• Contains business logic in services
• Depends only on the domain layer
• Orchestrates use cases using domain repositories

3. Interface Layer

• Contains HTTP controllers, routes, and middleware
• Depends on application and domain layers
• Translates between HTTP requests/responses and domain concepts

4. Infrastructure Layer

• Contains implementation details (database, email, etc.)
• Depends on domain interfaces
• Implements repository interfaces with concrete technology

📁 Project Structure

src/
├── config/                     # Configuration files
│   ├── database.ts            # Database connection
│   ├── logger.ts              # Winston logger
│   └── env.ts                 # Environment variables
│
├── domain/                     # Domain Layer (Core)
│   ├── entities/
│   │   ├── IBaseEntity.ts     # Base entity interface
│   │   └── IUser.ts           # User entity
│   ├── repositories/
│   │   ├── IGenericRepository.ts  # Generic CRUD interface
│   │   └── IUserRepository.ts     # User repository interface
│   ├── services/
│   │   └── IUserService.ts        # User service interface
│   └── shared/
│       ├── ApiResponse.ts         # Standard API response
│       └── AppError.ts            # Custom error class
│
├── application/                # Application Layer
│   ├── request-dtos/
│   │   └── IUserRequest.ts        # User request DTOs
│   └── services/
│       └── UserService.ts         # User business logic
│
├── interfaces/                 # Interface Layer
│   └── http/
│       ├── controllers/
│       │   └── UserController.ts  # HTTP handlers
│       ├── middlewares/
│       │   └── ErrorMiddleware.ts # Error handling
│       ├── routes/
│       │   └── UserRoutes.ts      # Route definitions
│       └── validation/
│           ├── schemas/
│           │   └── UserSchemas.ts # Joi validation
│           └── validator.ts       # Validation middleware
│
├── infrastructure/             # Infrastructure Layer
│   └── database/
│       └── mongodb/
│           ├── models/
│           │   ├── IBaseDocument.ts   # Base Mongoose doc
│           │   └── UserModel.ts       # User Mongoose model
│           └── repositories/
│               ├── BaseRepository.ts  # Generic repo implementation
│               └── UserRepository.ts  # User repo implementation
│
├── app.ts                      # Express app setup
├── server.ts                   # HTTP server
├── container.ts                # Dependency injection
├── bootstrap.ts                # Application bootstrap
└── index.ts                    # Entry point

🚀 Getting Started

Prerequisites

• Node.js >= 20.x
• MongoDB >= 6.x (or Docker)
• npm or yarn

Installation

1. Clone the repository

git clone https://github.com/yourusername/clean-architecture-nodejs.git
cd clean-architecture-nodejs

2. Install dependencies

npm install

3. Setup environment variables

cp .env.example .env
# Edit .env with your configuration

4. Start MongoDB (if using Docker)

docker run -d -p 27017:27017 --name mongodb mongo:latest

5. Run the application

# Development mode
npm run dev

# Production build
npm run build
npm start

The server will start on http://localhost:3000

🔌 API Endpoints

User Management

Register User

POST /api/users/register
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "password": "Password@123",
  "confirmPassword": "Password@123",
  "phoneNumber": "+1234567890"
}

Get All Users

GET /api/users?page=1&limit=10

Get User By ID

GET /api/users/:id

Update User

PUT /api/users/:id
Content-Type: application/json

{
  "firstName": "Jane",
  "phoneNumber": "+9876543210"
}

Delete User

DELETE /api/users/:id

Health Check

GET /health

Response:

{
  "status": "OK",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "uptime": 123.456
}

🌐 Environment Variables

Create a .env file in the root directory:

# Application
NODE_ENV=development
PORT=3000

# Database
MONGODB_URI=mongodb://localhost:27017/clean-architecture-db

# Logging
LOG_LEVEL=info

# JWT (for future authentication)
JWT_SECRET=your-super-secret-key-change-in-production
JWT_EXPIRES_IN=7d

# CORS
CORS_ORIGIN=*

💻 Development

Available Scripts

# Development with hot reload
npm run dev

# Development with tsx (faster)
npm run dev:tsx

# Build for production
npm run build

# Start production server
npm start

# Type checking
npm run compile

# Linting
npm run lint

# Format code
npm run format

Code Style

This project uses:

• ESLint for linting
• Prettier for code formatting
• TypeScript strict mode for type safety

🏭 Production Build

Build the project for production:

npm run build

This will:

1. Compile TypeScript to JavaScript
2. Resolve path aliases using tsc-alias
3. Output to the dist/ directory

Run in production:

npm start

Docker Deployment

Create a Dockerfile:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/index.js"]

Build and run:

docker build -t clean-architecture-api .
docker run -p 3000:3000 --env-file .env clean-architecture-api

🧪 Testing the API

Using cURL

Register a user:

curl -X POST http://localhost:3000/api/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "password": "Password@123",
    "confirmPassword": "Password@123"
  }'

Get all users:

curl http://localhost:3000/api/users?page=1&limit=10

Using Postman

Import the following collection:

{
  "info": {
    "name": "Clean Architecture API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Register User",
      "request": {
        "method": "POST",
        "header": [],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"email\": \"john@example.com\",\n  \"password\": \"Password@123\",\n  \"confirmPassword\": \"Password@123\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        },
        "url": {
          "raw": "http://localhost:3000/api/users/register",
          "protocol": "http",
          "host": ["localhost"],
          "port": "3000",
          "path": ["api", "users", "register"]
        }
      }
    }
  ]
}

🔄 Database-Agnostic Design

This architecture is completely database-agnostic. The business logic has zero knowledge of MongoDB, PostgreSQL, or any specific database.

How to Switch Databases

Example: Adding PostgreSQL Support

1. Install TypeORM and PostgreSQL driver:

npm install typeorm pg

2. Create PostgreSQL Repository:

// src/infrastructure/database/postgresql/repositories/UserRepository.ts
import { IUserRepository } from '@domain/repositories/IUserRepository';
import { Repository } from 'typeorm';

export class PostgresUserRepository implements IUserRepository {
  constructor(private repository: Repository<User>) {}
  
  async create(data: Partial<IUser>): Promise<IUser> {
    const user = this.repository.create(data);
    return await this.repository.save(user);
  }
  
  // ... implement all interface methods
}

3. Update Factory:

// src/infrastructure/database/factory.ts
export function createUserRepository(dbType: string): IUserRepository {
  switch (dbType) {
    case 'mongodb':
      return new MongoUserRepository();
    case 'postgresql':
      return new PostgresUserRepository(getTypeORMRepo());
    default:
      throw new Error(`Unsupported database: ${dbType}`);
  }
}

4. Update Environment:

DATABASE_TYPE=postgresql
DATABASE_URL=postgresql://user:pass@localhost:5432/db

That's it! Your business logic remains completely unchanged.

Supported ORMs

You can use any ORM you prefer:

• Mongoose (MongoDB) - Current implementation
• TypeORM (PostgreSQL, MySQL, SQLite, etc.)
• Prisma (PostgreSQL, MySQL, SQLite, etc.)
• Sequelize (PostgreSQL, MySQL, MariaDB, etc.)

The Repository Pattern ensures your business logic stays clean regardless of your database choice.

🎨 Design Patterns Used

• Clean Architecture - Separation of concerns
• Repository Pattern - Data access abstraction
• Dependency Injection - Loose coupling
• Factory Pattern - Object creation
• DTO Pattern - Data transfer objects
• Middleware Pattern - Request/response processing

📚 Key Takeaways

1. Separation of Concerns - Each layer has a single responsibility
2. Dependency Inversion - High-level modules don't depend on low-level modules
3. Database Independence - Easy to switch databases
4. Testability - Business logic is isolated and easily testable
5. Maintainability - Clear structure makes code easy to understand
6. Scalability - Well-organized for growing codebases

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Clean Architecture by Robert C. Martin (Uncle Bob)
• Node.js Best Practices
• TypeScript Community

📧 Contact

• 💼 LinkedIn: https://www.linkedin.com/in/sandesh-rathnayake-511694141
• 📘 Facebook: https://www.facebook.com/sandesh.rathnayake

Project Link: https://github.com/sandeshR98/nodejs-clean-architecture

---

⭐ If you find this project helpful, please give it a star!