Skip to content

Latest commit

 

History

17 Commits

Folders and files

Repository files navigation

🚀 Node.js Full Course 2026 — Production Backend Capstone

A production-grade backend capstone project built with Node.js, TypeScript, PostgreSQL, Redis, BullMQ, Cloudinary, and JWT, demonstrating real-world backend architecture, authentication, caching, background processing, and scalable API design.


📌 Project Overview

This project is the final capstone backend application for a comprehensive Node.js development journey.

The goal is to go beyond basic CRUD APIs and build a backend that follows production-ready engineering practices.

The application implements a role-based system with two primary roles:

  • 👤 User
  • 🛡️ Admin

It combines authentication, task management, database architecture, caching, rate limiting, background jobs, file management, logging, and centralized error handling into one complete backend system.


✨ Core Features

🔐 Authentication & Authorization

  • JWT-based authentication
  • Google OAuth authentication
  • Secure password handling
  • Role-based authorization
  • Protected routes
  • User/Admin access control

📋 Task Management

Users can manage support tasks through a complete CRUD system.

  • Create tasks
  • View tasks
  • Update tasks
  • Delete tasks
  • Task ownership
  • Administrative oversight
  • Role-based task operations

⚡ Redis Caching

Redis is integrated to improve API performance.

The project follows the Cache-Aside Pattern:

Client
   │
   ▼
API
   │
   ▼
Redis
   │
   ├── Cache Hit ──────► Return Data
   │
   └── Cache Miss
           │
           ▼
       PostgreSQL
           │
           ▼
       Store in Redis
           │
           ▼
       Return Data

Redis is used for:

  • API caching
  • Banner caching
  • Rate limiting
  • Fast temporary data access
  • Pub/Sub capabilities

📨 Background Jobs with BullMQ

Long-running or non-critical operations are handled asynchronously using BullMQ.

For example, Cloudinary image deletion does not need to block the main API request.

API Request
    │
    ▼
Backend
    │
    ├── Main Operation ──────► Response
    │
    └── Add Job
          │
          ▼
       Redis
          │
          ▼
       BullMQ
          │
          ▼
        Worker
          │
          ▼
      Cloudinary

Background Job Use Cases

  • Cloudinary image deletion
  • Heavy processing
  • Notifications
  • Cleanup operations
  • Other asynchronous tasks

This approach keeps API responses fast and prevents unnecessary blocking.


🗄️ Database Architecture

The application uses PostgreSQL as its primary relational database.

PostgreSQL runs in a Docker-based development environment.

Database Responsibilities

  • User data
  • Authentication information
  • Roles
  • Tasks
  • Relationships
  • Persistent application data

🔄 Database Migrations

The project includes automated SQL migration management for maintaining database schema changes.

Migration-based development provides:

  • Version-controlled schema changes
  • Reproducible database setup
  • Safer production deployments
  • Organized database evolution

Example:

migrations/
├── 001_create_users.sql
├── 002_create_tasks.sql
├── 003_add_auth_fields.sql
└── 004_update_task_schema.sql

🏗️ Project Architecture

The project separates responsibilities into different layers.

                    ┌─────────────────┐
                    │     Client      │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │   Controllers   │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │    Services     │
                    │ Business Logic  │
                    └────────┬────────┘
                             │
                  ┌──────────┴──────────┐
                  │                     │
                  ▼                     ▼
          ┌──────────────┐       ┌──────────────┐
          │ Repository   │       │ External APIs│
          │ SQL Queries  │       │  Cloudinary  │
          └───────┬──────┘       └──────────────┘
                  │
                  ▼
          ┌──────────────┐
          │  PostgreSQL  │
          └──────────────┘

                  Redis
                    │
          ┌─────────┴─────────┐
          │                   │
       Caching            Rate Limit
          │
       BullMQ
          │
       Workers

📁 Project Structure

project/
│
├── source/
│   ├── controllers/
│   ├── routes/
│   ├── middlewares/
│   ├── validators/
│   ├── config/
│   └── app.ts
│
├── repository/
│   ├── user.repository.ts
│   ├── task.repository.ts
│   └── ...
│
├── services/
│   ├── auth/
│   ├── cloudinary/
│   ├── redis/
│   ├── queue/
│   └── ...
│
├── constants/
│   └── index.ts
│
├── migrations/
│   ├── 001_*.sql
│   ├── 002_*.sql
│   └── ...
│
├── workers/
│   └── ...
│
├── package.json
├── tsconfig.json
├── docker-compose.yml
└── README.md

🧠 Layer Responsibilities

🎮 Controllers

Controllers are responsible for handling HTTP requests and responses.

Request
   ↓
Controller
   ↓
Service
   ↓
Response

They should remain lightweight and delegate business logic to the service layer.


⚙️ Services

The service layer contains the application's business logic.

Examples:

  • Authentication logic
  • Task management
  • Cloudinary operations
  • Redis operations
  • Background job creation

This keeps business rules separate from HTTP-specific code.


🗃️ Repository

The repository layer handles database operations.

Service
   │
   ▼
Repository
   │
   ▼
PostgreSQL

Responsibilities include:

  • SQL queries
  • Database interaction
  • Data retrieval
  • Data persistence

This separation makes database logic easier to maintain and test.


🛡️ Centralized Error Handling

The project uses a custom AppError class for consistent application errors.

Instead of handling errors differently in every controller, errors are passed to centralized middleware.

Controller
    │
    ▼
Service
    │
    └── AppError
          │
          ▼
   Error Middleware
          │
          ▼
     HTTP Response

Benefits

  • Consistent error responses
  • Cleaner controllers
  • Easier debugging
  • Centralized error management
  • Better maintainability

🚦 Rate Limiting

Redis is used to implement distributed rate limiting.

Rate limiting protects APIs from:

  • Excessive requests
  • Abuse
  • Brute-force attempts
  • Unnecessary server load

Example:

Client
  │
  │ Request
  ▼
Rate Limiter
  │
  ▼
Redis
  │
  ├── Within Limit ──► API
  │
  └── Limit Exceeded ──► 429 Too Many Requests

Using Redis allows rate-limit state to be shared across multiple backend instances.


☁️ Cloudinary Integration

Cloudinary is used for file and image management.

The application integrates Cloudinary with Multer middleware for handling uploaded files.

Upload Flow

Client
   │
   │ Multipart Upload
   ▼
Multer
   │
   ▼
Backend
   │
   ▼
Cloudinary
   │
   ▼
Image URL
   │
   ▼
PostgreSQL

For deletion, the operation can be processed asynchronously using BullMQ.


📝 Logging with Pino

The project uses Pino Logger for structured application logging.

Logging helps with:

  • Debugging
  • Monitoring
  • Error investigation
  • Production troubleshooting
  • Request tracking

Example:

INFO  Server started
INFO  Database connected
INFO  Redis connected
INFO  User authenticated
WARN  Rate limit approaching
ERROR Cloudinary operation failed

🔑 Authentication Flow

JWT Authentication

User
 │
 │ Login
 ▼
Auth Controller
 │
 ▼
Auth Service
 │
 ▼
Verify Credentials
 │
 ▼
Generate JWT
 │
 ▼
Client

For protected requests:

Client
 │
 │ Authorization: Bearer <token>
 ▼
Authentication Middleware
 │
 ▼
Verify JWT
 │
 ▼
Attach User
 │
 ▼
Controller

🌐 Google OAuth

The application also supports Google OAuth authentication.

User
 │
 ▼
Google
 │
 ▼
OAuth Callback
 │
 ▼
Backend
 │
 ▼
Find/Create User
 │
 ▼
Generate Authentication Token
 │
 ▼
Client

This provides users with an alternative authentication method while keeping identity management centralized.


👥 Role-Based Access Control

The system supports different permissions based on user roles.

                 User
                  │
           ┌──────┴──────┐
           │             │
        User Role     Admin Role
           │             │
           ▼             ▼
     User Features   Admin Features

Example:

Feature User Admin
Register/Login ✅ ✅
Manage Own Tasks ✅ ✅
View Tasks ✅ ✅
Administrative Oversight ❌ ✅
User Management ❌ ✅

🔌 API Design

The backend follows RESTful API design principles.

Example Endpoints

POST   /api/auth/register
POST   /api/auth/login
GET    /api/auth/me

POST   /api/tasks
GET    /api/tasks
GET    /api/tasks/:id
PATCH  /api/tasks/:id
DELETE /api/tasks/:id

HTTP Methods

Method Purpose
GET Retrieve resources
POST Create resources
PATCH Partially update resources
DELETE Delete resources

🧰 Tech Stack

Technology Purpose
Node.js Backend runtime
TypeScript Type-safe development
PostgreSQL Primary database
Redis Caching & rate limiting
BullMQ Background job processing
Cloudinary Image/file storage
Multer Multipart file handling
Pino Structured logging
JWT Authentication
Google OAuth Social authentication
Docker PostgreSQL development environment

🧪 Production-Grade Concepts

This capstone focuses on concepts commonly used in real-world backend systems.

Architecture

  • Layered architecture
  • Separation of concerns
  • Repository pattern
  • Service layer
  • Centralized error handling

Database

  • PostgreSQL
  • SQL queries
  • Database migrations
  • Transactions
  • Data relationships

Performance

  • Redis caching
  • Cache-aside pattern
  • Rate limiting
  • Background processing

Authentication

  • JWT
  • Google OAuth
  • Role-based authorization
  • Protected routes

Infrastructure

  • Docker
  • Redis
  • Background workers
  • External cloud storage

Observability

  • Structured logging
  • Centralized error handling
  • Request monitoring

🔥 Complete Request Lifecycle

A typical request can flow through multiple layers:

Client
  │
  ▼
Route
  │
  ▼
Middleware
  │
  ├── Authentication
  ├── Authorization
  ├── Validation
  └── Rate Limiting
  │
  ▼
Controller
  │
  ▼
Service
  │
  ├───────────────┐
  ▼               ▼
Repository      Redis
  │               │
  ▼               │
PostgreSQL        │
                  │
                  ▼
              Response

For asynchronous work:

Service
   │
   ▼
BullMQ Queue
   │
   ▼
Redis
   │
   ▼
Worker
   │
   ▼
External Service

📈 Performance Strategy

The backend uses multiple techniques to improve performance and scalability.

1. Redis Cache

Frequently accessed data is cached to reduce database load.

2. Rate Limiting

Protects backend resources from excessive traffic.

3. Background Jobs

Expensive operations are moved away from the request-response cycle.

4. Repository Layer

Database access remains organized and reusable.

5. Structured Logging

Makes production debugging and monitoring easier.


🚀 Getting Started

1. Clone the Repository

git clone <https://github.com/yeasin-riyad/nodejs-capstone-project.git>

cd <nodejs-capstone-project>

2. Install Dependencies

npm install

3. Start PostgreSQL with Docker

docker compose up -d

4. Configure Environment Variables

Create a .env file:

NODE_ENV=development

PORT=5000

DATABASE_URL=your_postgresql_connection_string

JWT_SECRET=your_jwt_secret

REDIS_URL=redis://localhost:6379

CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

5. Run Database Migrations

npm run migrate

6. Start Development Server

npm run dev

🧪 Testing

The project can be extended with automated tests for:

  • Authentication
  • Authorization
  • Task CRUD
  • Repository methods
  • Service logic
  • Redis caching
  • Rate limiting
  • Background jobs
  • API endpoints

Recommended testing strategy:

Unit Tests
    │
    ▼
Integration Tests
    │
    ▼
API Tests
    │
    ▼
End-to-End Tests

📚 What I Learned

Building this capstone helped strengthen my understanding of production backend development.

Backend Fundamentals

  • Node.js architecture
  • Express.js
  • TypeScript
  • REST API design
  • Middleware
  • Error handling

Database

  • PostgreSQL
  • SQL
  • Repository pattern
  • Database migrations
  • Relational data modeling

Authentication

  • JWT
  • Google OAuth
  • Role-based authorization
  • Protected routes

Performance

  • Redis
  • Cache-aside pattern
  • Rate limiting
  • Background processing

Infrastructure & Production

  • Docker
  • BullMQ
  • Cloudinary
  • Pino logging
  • Asynchronous architecture

🎯 Key Takeaways

A production backend is much more than CRUD APIs.

The most important lessons from this project are:

  1. Separate business logic from HTTP logic.
  2. Use repositories to keep database access organized.
  3. Use Redis when caching can reduce database load.
  4. Move expensive operations to background workers.
  5. Use centralized error handling for consistent APIs.
  6. Protect APIs with authentication, authorization, and rate limiting.
  7. Use structured logging to make production debugging easier.
  8. Design the system so individual components can evolve independently.

🗺️ Backend Architecture Journey

Node.js
   │
   ▼
Express.js
   │
   ▼
TypeScript
   │
   ▼
REST API
   │
   ▼
PostgreSQL
   │
   ▼
Authentication
   │
   ▼
Redis
   │
   ▼
Rate Limiting
   │
   ▼
Cloudinary
   │
   ▼
BullMQ
   │
   ▼
Background Workers
   │
   ▼
Production-Ready Backend 🚀

👨‍💻 Author

Md. Yeasin Mazumder

Backend Developer | Full-Stack Enthusiast | Problem Solver

Interested in building scalable backend systems, distributed architectures, and production-ready applications.


⭐ Support

If you find this project useful or it helps you learn backend development, consider giving the repository a ⭐.

Happy Coding! 🚀