Features • Architecture • Getting Started • Docker • API • Benchmark

Rate Limiter Service

A production-ready distributed Rate Limiter Service built using Node.js, Express.js, Redis, PostgreSQL, Prisma ORM, Docker, and Nginx.

---

📖 Overview

Rate Limiter Service is a production-ready backend application that implements the Token Bucket Algorithm to efficiently control API traffic. The project is horizontally scalable using multiple Node.js instances behind an Nginx Load Balancer while maintaining a shared bucket state through Redis and persistent configuration in PostgreSQL.

✨ Features

🚀 Core Functionality

• Implements the Token Bucket Algorithm for efficient API rate limiting.
• Supports configurable capacity and refill rate for each client.
• Provides Admin APIs to create, update, retrieve, and delete client configurations.
• Maintains persistent client configurations in PostgreSQL.

---

⚡ High Performance

• Stores bucket state in Redis for fast read/write operations.
• Caches client configurations in Redis to minimize unnecessary database queries.
• Automatically refills tokens based on the configured refill rate.
• Designed to handle high request throughput with low latency.

---

📈 Scalability

• Supports horizontal scaling with multiple Node.js application instances.
• Uses Nginx Round Robin Load Balancer to distribute incoming traffic.
• Ensures consistent rate limiting across all application instances using shared Redis and PostgreSQL.

---

🐳 Containerization

• Fully containerized using Docker.
• Multi-container orchestration with Docker Compose.
• Automatically applies pending Prisma migrations during container startup.

---

🛡 Reliability

• Input validation using Zod.
• Structured request logging with Pino.
• Unique request IDs for easier debugging and tracing.
• Graceful shutdown to safely close database and Redis connections.

---

📖 Developer Experience

• Interactive API documentation using Swagger UI.
• Environment-based configuration using .env.
• Clean layered architecture (Controllers → Services → Repositories).
• Performance tested using Autocannon.

🏗️ Architecture

The application follows a distributed architecture to provide high performance, scalability, and consistency.

Request Flow

1. A client sends a request to the Nginx Load Balancer.
2. Nginx distributes incoming traffic across multiple Node.js application instances using the Round Robin strategy.
3. Each application instance retrieves the client configuration from Redis Cache. If the configuration is unavailable, it is fetched from PostgreSQL and cached for future requests.
4. The current bucket state is stored and updated in Redis, enabling all application instances to share the same rate-limiting state.
5. The Token Bucket Algorithm determines whether the request should be allowed or rejected based on the available tokens.
6. The updated bucket state is written back to Redis, and the API responds with the remaining token count.

Why This Architecture?

• ⚡ Fast – Redis provides low-latency access for bucket state and cached client configurations.
• 📈 Scalable – Multiple application instances can be added behind Nginx without changing the application logic.
• 🔄 Consistent – Shared Redis ensures all instances enforce the same rate limits.
• 🗄️ Reliable – PostgreSQL acts as the persistent source of truth for client configurations.
• 🐳 Portable – Docker Compose enables the complete stack to run consistently across development and deployment environments.

🛠 Tech Stack

Node.js • Express.js • PostgreSQL • Redis • Prisma ORM • Docker • Nginx • Git • GitHub • Postman • VS Code • Swagger UI • Zod • Pino • Autocannon

📁 Project Structure

Rate-Limiter-Service
│
├── 📂 assets          # README images
├── 📂 nginx           # Nginx Load Balancer configuration
├── 📂 prisma          # Prisma schema & migrations
├── 📂 src
│   ├── config         # Database, Redis & Logger configuration
│   ├── controllers    # Request handlers
│   ├── middlewares    # Validation & logging middlewares
│   ├── repositories   # Database access layer
│   ├── routes         # API routes
│   ├── services       # Business logic
│   ├── utils          # Utility functions
│   ├── validations    # Zod validation schemas
│   ├── app.js
│   └── server.js
│
├── .dockerignore
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md

🚀 Getting Started

Prerequisites

Before running the project, ensure you have the following installed:

• Node.js (v22 or later)
• PostgreSQL
• Redis
• Docker & Docker Compose (optional, recommended)

---

Clone the Repository

git clone https://github.com/<your-username>/Rate-Limiter-Service.git
cd Rate-Limiter-Service

---

Install Dependencies

npm install

---

Environment Variables

Create a .env file in the project root using .env.example.

Run the Application

Development

"npm run dev" or "nodemon"

Production

npm start

🐳 Docker Setup

Build and start all services

docker compose up --build

Run in detached mode

docker compose up -d

Stop all containers

docker compose down

The Docker Compose setup includes:

• Nginx – Load Balancer
• Node.js App 1
• Node.js App 2
• Redis
• PostgreSQL

📡 API Endpoints

Admin APIs

Method	Endpoint	Description
POST	/admin/client	Create a new client configuration
GET	/admin/client	Retrieve all client configurations
GET	/admin/client/:clientId	Retrieve a specific client configuration
PUT	/admin/client/:clientId	Update an existing client configuration
DELETE	/admin/client/:clientId	Delete a client configuration

---

Rate Limiter API

Method	Endpoint	Description
POST	/rate-limiter/check	Validate request and consume a token using the Token Bucket Algorithm

📖 API Documentation

Interactive API documentation is available through Swagger UI, allowing you to explore and test all endpoints directly from the browser.

Default URL

http://localhost:3000/api-docs

📊 Performance Benchmark

The service was benchmarked using Autocannon to evaluate throughput and latency under concurrent load.

Benchmark Command

npx autocannon -c 200 -d 20 -m POST \
-H "Content-Type: application/json" \
-b '{"clientId":"docker-test"}' \
http://localhost:3000/rate-limiter/check

Benchmark Result

The benchmark demonstrates the application's ability to handle concurrent requests while maintaining low response latency through Redis caching and horizontal scaling with Nginx.

👨‍💻 Author

Naveen Kumar