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

1. Install and use Node.js via nvm

   nvm install
   nvm use

2. Install dependencies

   npm install

3. Create environment file

   cp .env.example .env

4. Start PostgreSQL database

   docker compose up -d

5. Run database migrations

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

6. Generate Prisma client

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

7. Start development server

   npm run dev

8. 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.