JamieLivingstone/node-clean-architecture

README

Node Clean Architecture

A production-ready Node.js template following Clean Architecture principles, designed for scalability and maintainability.

✨ Features

Modern Stack — Fastify, Prisma, Zod, Vitest, Biome, and TypeScript
High Performance — Built on Fastify for maximum throughput (benchmarks)
Type Safe — Strict TypeScript with runtime validation via Zod
Database Ready — Prisma ORM with migrations and type-safe queries
API Documentation — Auto-generated Swagger/OpenAPI from route schemas
Production Ready — Structured logging, rate limiting, security headers, health checks
Test First — Unit and integration testing with isolated database schemas

🚀 Getting Started

Prerequisites

nvm (Node Version Manager)
Docker running locally

Installation

Install and use Node.js via nvm
```
nvm install
nvm use
```
Install dependencies
```
npm install
```
Create environment file
```
cp .env.example .env
```
Start PostgreSQL database
```
docker compose up -d
```

Run database migrations

npx prisma migrate deploy --config prisma/prisma.config.ts

Generate Prisma client

npx prisma generate --config prisma/prisma.config.ts

Start development server
```
npm run dev
```
Navigate to Swagger http://localhost:3000/api-docs

📜 Scripts

Development

npm run dev       # Start dev server with hot reload
npm run build     # Build for production

Code Quality

npm run lint      # Check for lint and format issues
npm run lint:fix  # Auto-fix lint and format issues
npm run format    # Format code with Biome

Testing

npm test                 # Run all tests
npm run test:unit        # Run unit tests only
npm run test:integration # Run integration tests

Database

npx prisma migrate deploy --config prisma/prisma.config.ts  # Apply pending migrations
npx prisma migrate dev --config prisma/prisma.config.ts     # Create a new migration
npx prisma studio --config prisma/prisma.config.ts          # Open database GUI

🏛️ Clean Architecture

This template implements Clean Architecture principles:

Layer	Purpose	Dependencies
Domain	Business logic, entities, repository interfaces	None
Infrastructure	Database, logging, external services	Domain
Features	Use cases and HTTP controllers	Domain, Infrastructure

The Dependency Rule: Source code dependencies point inward. Domain knows nothing about infrastructure or HTTP.

📁 Project Structure

src/
├── domain/           # Core business logic (no dependencies)
│   ├── entities/     # Domain models
│   └── repositories/ # Repository interfaces
├── infrastructure/   # External concerns
│   ├── config/       # Environment configuration
│   ├── logger/       # Structured logging
│   ├── repositories/ # Repository implementations
│   └── di.ts         # Dependency injection
├── features/         # Application use cases
│   └── {feature}/
│       ├── {feature}-controller.ts  # HTTP routes
│       └── {operation}.ts           # Business operations
├── plugins/          # Fastify plugins
├── app.ts            # Application setup
└── server.ts         # Entry point

📄 License

This project is licensed under the MIT License.