NestJS - Clean Architecture Boilerplate

📝 Table of content

• 👋 Introduction
• 🚀 Quick Start
• 🌟 Key Features
• 📖 API Documentation
• 📂 Project Structure

👋 Introduction

Welcome to the NestJS Boilerplate. This project provides a solid foundation for building scalable and maintainable backend applications with NestJS, following the Clean Architecture. It also integrates concepts from Domain-Driven Design (DDD) to help organize your code around the core business logic.

🚀 Quick Start

Important

To run the backend locally, you need a PostgreSQL database with migrations applied.

1. Clone the project

git clone git@github.com:Gi-jutsu/nestjs-clean-boilerplate.git
cd nestjs-clean-boilerplate

2. Bootstrap the PostgreSQL database

2.1. Start PostgreSQL using docker-compose.yaml

docker compose -f docker/docker-compose.yaml up database -d

2.2. Run the SQL migrations

pnpm drizzle-kit migrate

3. Start the API

You can run the backend either locally or with Docker.

Option A: Run locally (watch mode)

pnpm dev

Otpion B: Run with Docker

docker compose -f docker/docker-compose.yaml up api -d

🌟 Key Features

📬 Outbox Pattern

• Guaranteed Event Delivery: ensure events are reliably stored and dispatched achieving at-least-once delivery.
• Concurrency: Leverages REPEATABLE READ isolation and FOR UPDATE SKIP LOCKED to ensure efficient and exclusive message processing, even under high load.
• Transaction Safety: Events are saved in the outbox as part of the same database transaction as aggregate updates, ensuring consistency.

🐳 Docker-Ready

• Optimized for Deployments: Multi-stage build keeps the production image lean, reducing network footprint and speeding up deployments.

• Run Locally: Launch the entire stack (API + Database) with docker-compose.yaml

• Security: Runs as a non-root user to reduce security risks

📂 Project Structure

📁 src/
├── 📁 identity-and-access/
│ ├── 📁 domain/ # Business logic (e.g. Account, ForgotPasswordRequest ...)
│ ├── 📁 infrastructure/ # Driver adapters (e.g., Jwt, Mailer, etc.)
│ ├── 📁 use-cases/ # Implements business use cases, connecting ports and domains
│ └── 📄 identity-and-access.module.ts
│
├── 📁 shared-kernel/
│ ├── 📁 domain/ # Shared logic and core domain concepts (e.g., AggregateRoot, DomainEvent, Outbox Message, Shared Errors)
│ ├── 📁 infrastructure/ # Driver adapters used across multiple bounded-contexts (e.g. GoogleCloudTasks, ...)
│ ├── 📁 use-cases/
│ ├── 📁 utils/
│ └── 📄 shared-kernel.module.ts
│
├── 📄 application.module.ts
└── 📄 main.ts