Backend Template Project

A modern NestJS backend template with Nx build system, featuring modular architecture and scalable services.

📑 Table of Contents

• Backend Template Project
  • 📑 Table of Contents
  • 🚀 Features
  • 📋 Prerequisites
  • 🛠️ Quick Start
    • 🧪 First-Time Run Without Docker
    • 🐳 Using Full Docker Setup
  • 🏗️ Project Structure
  • 🚀 Scripts
  • 🔧 Configuration
    • Environment Variables
    • Database Configuration
      • For PostgreSQL (production)
      • For SQLite (development/testing)
  • 🧪 Testing
  • 📚 API Usage Guide
  • 🔐 Security
  • 🐳 Docker
    • Development
    • Production
  • 📦 Dependencies
    • Main Dependencies
    • Development Dependencies
  • 🛠️ TODO / To Improve

🚀 Features

• NestJS Framework: Modern Node.js framework
• TypeScript: Strong typing
• Nx Build System: Monorepo support
• Database:
  • PostgreSQL (production)
  • SQLite (development)
  • Easy DB switching via env vars
• Auth: JWT + Passport
• API Docs: Swagger/OpenAPI
• Caching: Redis + @nestjs/cache-manager
• Queue: BullMQ
• Testing: Jest (unit/E2E) + Vitest (unit advanced)
• Docker: Dev/Prod configurations

↑ Go to top

📋 Prerequisites

• Node.js >= 22.15.1
• Yarn >= 4.9.1
• PostgreSQL >= 17 or SQLite3
• Redis >= 6.2.0
• Docker and Docker Compose

↑ Go to top

---

🛠️ Quick Start

# Install dependencies
yarn install

# Set up environment variables
cp .env.example .env

# Seed the database
yarn seed

💡 Note: The yarn seed command populates database.sqlite3 for development. This file is shared with Docker via volume, so Docker will use the same seeded database when running in development mode.

🧪 First-Time Run Without Docker

If you want to run the app without full Docker (e.g., just locally with yarn start) but don't have Redis installed:

# Start Redis via Docker
docker compose up -d redis

# Then start the app locally
yarn start

🐳 Using Full Docker Setup

💡 Note: The development environment uses SQLite3 for lighter setup. More here.

# Run the development environment
docker compose up -d

This will launch:

• the application
• Redis
• and use the pre-seeded database.sqlite3 file

↑ Go to top

🏗️ Project Structure

.
├── apps/
│   ├── service-a/         # Main app
│   └── service-a-e2e/     # E2E tests
├── libs/
│   ├── modules/          # Shared modules
│   │   ├── auth/         # Auth
│   │   └── ...           # Various modules
│   ├── entities/         # Database entities
│   ├── db/               # Database configuration
│   └── utils/            # Shared helpers & utility functions
├── docs/                 # Documentation
└── config files          # Various configs

↑ Go to top

🚀 Scripts

yarn start     # Run dev server
yarn build     # Build app
yarn seed      # Seed DB
yarn test:unit # Unit tests
yarn test:e2e  # E2E tests

↑ Go to top

🔧 Configuration

Environment Variables

# App
PORT=3000

# Database Configuration
DB_TYPE=postgres # or sqlite
SQLITE_STORAGE=./database.sqlite3  # Only used when DB_TYPE=sqlite

# PostgreSQL Configuration (when DB_TYPE=postgres)
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=app_db

# JWT
JWT_SECRET=your-secret
JWT_EXPIRATION=1h

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

Database Configuration

The project supports both PostgreSQL and SQLite databases. You can switch between them using the DB_TYPE environment variable:

For PostgreSQL (production)

DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=app_db

For SQLite (development/testing)

DB_TYPE=sqlite
SQLITE_STORAGE=./database.sqlite3

↑ Go to top

🧪 Testing

• Unit Tests: Jest & Vitest (*.spec.ts)

  • Run with yarn test:unit

• E2E Tests: Jest (apps/service-a-e2e)

  • Run with yarn test:e2e

• Coverage: Reports in coverage/

  • Use flag --coverage when running tests

ℹ️ Note: If you're running yarn test:e2e, consider using a dedicated .env.test file instead of .env.local. This ensures you do not accidentally seed or connect to your development or production database during E2E tests.

You can do this by copying and editing the default env:

cp .env.example .env.test

Then configure .env.test to use SQLite or a separate test database.

↑ Go to top

📚 API Usage Guide

http://localhost:3000

For step-by-step instructions on registering, logging in, and using protected endpoints, see the API Usage Guide.

Features:

• Interactive API documentation
• Request/response examples
• Authentication support
• Downloadable OpenAPI specification:
  • http://localhost:3000/openapi.json

↑ Go to top

🔐 Security

• Authentication:

  • JWT-based authentication with Passport.js
  • Secure password hashing with bcrypt
  • Protected routes using JwtAuthGuard

• Data Protection:

  • Environment variable management
  • Input validation using class-validator and NestJS ValidationPipe:
    • Auto-transforms inputs to expected types
    • Whitelists only allowed fields
    • Forbids unexpected properties
  • Secure session/token handling
  • SQL injection prevention

• App-level Security:

  • helmet for setting HTTP headers (e.g., disabling X-Powered-By, frameguard, XSS protection)
  • Rate limiting per IP (default: 100 requests/minute)
  • CORS enabled with domain restriction via CORS_ORIGIN environment variable
  • Trust proxy setup for reverse proxies (e.g., Nginx)

↑ Go to top

🐳 Docker

The project includes Docker configuration for development and production:

Development

docker compose up -d

Services:

• Application service
• SQLite
• Redis for caching and queues

Production

docker compose -f docker-compose.production.yml up -d

Services:

• Application service
• PostgreSQL
• Redis for caching and queues

↑ Go to top

📦 Dependencies

Main Dependencies

• @nestjs/*: Core NestJS packages
• sequelize: ORM for database operations
• bullmq: Queue management
• passport: Authentication
• class-validator: Input validation
• swagger: API documentation

Development Dependencies

• nx: Build system
• jest & vitest: Testing frameworks
• eslint: Code linting
• prettier: Code formatting
• typescript: TypeScript support

↑ Go to top

🛠️ TODO / To Improve

• Infrastructure

  • Add Kubernetes deployment configuration
  • Add Terraform setup for infrastructure provisioning

• API Testing

  • Expand Postman collection with full test coverage
  • Automate Postman workflows using Newman (CI-ready)

• Architecture

  • Refactor project structure for microservices support
  • Extract Auth and Transactions into separate services

• DevOps / CI-CD

  • Add GitHub Actions / GitLab CI pipelines
  • Integrate Docker image build & push

• Monitoring & Observability

  • Add logging (e.g., Winston / Pino)
  • Setup Prometheus + Grafana or another monitoring stack

• Security Enhancements

  • Add rate limiting per endpoint group
  • Add CSRF/XSS protection for future frontend interactions

↑ Go to top