NebulaAPI Backend - Comprehensive Case Study

Enterprise-grade microservices backend with 50+ API endpoints, real-time WebSocket communication, AWS DynamoDB, video/image/PDF processing, JWT authentication, payment integration, and comprehensive API usage tracking

NestJS 11TypeScriptAWS DynamoDBSocket.ioFFmpeg

5 months

duration

Solo Developer

team Size

60,000+

lines Of Code

50+

api Endpoints

microservices

AWS

deployment

Project Overview

NebulaAPI Backend is an enterprise-grade microservices platform built with NestJS 11 and TypeScript 5.7, serving as the backbone for a comprehensive API gateway. The system handles 50+ API endpoints across 4 microservices (api-gateway, nebulaapi, converters, features) with AWS DynamoDB for data persistence, Socket.io for real-time communication, and integration with AWS S3, Cashfree, FFmpeg, Puppeteer, and OpenCV4.

Key features include JWT authentication with refresh tokens, subscription management with 30-day billing cycles, video compression with FFmpeg optimization, PDF conversion APIs (HTML/Word/Images), image processing with OpenCV4 Python integration, real-time chat and notifications via WebSocket, API usage tracking with daily/monthly aggregation, and comprehensive file upload handling with plan-based limits. Deployed on AWS with 99.99% uptime.

Technical Challenges

Building scalable microservices architecture with NestJS handling 50+ API endpoints

Implementing real-time bidirectional WebSocket communication with Socket.io for chat and notifications

Designing NoSQL database schema with AWS DynamoDB for 6+ tables with composite keys

Integrating multiple third-party services: AWS S3, Cashfree, Nodemailer, Puppeteer, FFmpeg

Building video compression API with FFmpeg optimization (CRF 18-28, resolution-based logic)

Implementing JWT authentication with 15-minute token expiry and automatic refresh mechanism

Creating subscription management with 30-day billing cycles and proration logic

Developing image processing APIs with OpenCV4 Python integration via child processes

Implementing comprehensive API usage tracking across all endpoints with daily/monthly aggregation

Building PDF conversion APIs (HTML-to-PDF, Word-to-PDF, PDF-to-Images) with Puppeteer and Ghostscript

Architecture & Design Decisions

NestJS Microservices Architecture

Implemented modular monorepo with 4 microservices (api-gateway, nebulaapi, converters, features) using NestJS 11. Each service has independent modules, controllers, and services with shared common library for cross-cutting concerns.

Improved maintainability, scalability, and team collaboration

AWS DynamoDB NoSQL Design

Designed schemaless database with 6 tables (Users, Reviews, Chats, Documents, PushNotifications, UploadedFiles) using composite keys (provider#email) and pay-per-request billing. Implemented BaseDynamoDBService for CRUD operations.

99.99% availability, automatic scaling, reduced costs

Socket.io Real-time Gateway

Built WebSocket gateway with @nestjs/platform-socket.io for bidirectional communication. Implemented room-based messaging, connection tracking, and automatic reconnection with fallback to polling.

Sub-100ms latency, 1000+ concurrent connections

JWT + Refresh Token Strategy

Implemented secure authentication with 15-minute access tokens and 7-day refresh tokens. Built ApiAuthGuard middleware for route protection and automatic token validation with 10-minute intervals.

Enhanced security, reduced token theft risk

Core Features Implemented

Authentication & Authorization

JWT-based authentication with bcrypt password hashing

Google OAuth 2.0 integration with provider-based composite keys

Refresh token mechanism with automatic rotation

ApiAuthGuard middleware for protected routes

Session management with token expiration tracking

Password reset flow with email verification

Converter APIs (6 Endpoints)

PDF-to-Images: Ghostscript integration, multi-page support, DPI control

HTML-to-PDF: Puppeteer rendering, custom page sizes, header/footer

Word-to-PDF: Mammoth.js + PDFKit conversion pipeline

Img-to-PDF: Multi-image PDF generation with layout options

Video-Compress: FFmpeg optimization with CRF 18-28, resolution scaling

Image-Resize: OpenCV4 Python integration with 4 resize modes

Feature APIs (1 Endpoint)

Image-Match: Computer vision similarity detection with OpenCV

File upload support with multipart/form-data

URL-based processing for remote files

Plan-based file size limits (Free: 10MB, Pro: 50MB, Enterprise: 200MB)

Format validation with MIME type checking

Real-time processing with progress tracking

Payment & Subscription

Cashfree payment gateway integration with order creation

Subscription plan management (Free, Pro, Enterprise)

30-day billing cycle with automatic renewal

Proration logic for plan upgrades/downgrades

Usage limit enforcement with API call tracking

Billing reset service with cron job scheduling

Real-time Communication

Socket.io WebSocket gateway with room-based messaging

Live support chat with admin reply system

Real-time notifications for account events

Connection tracking with user session management

Automatic reconnection with exponential backoff

Event-driven architecture for scalability

File Storage & Processing

AWS S3 integration with @aws-sdk/client-s3

Cloudflare R2 storage for processed files

Multipart file upload with Multer

File compression with Sharp and JSZip

Temporary file cleanup with OS tmpdir

Presigned URL generation for secure downloads

API Management

API usage tracking with TrackApiUsage decorator

Daily/monthly usage aggregation in DynamoDB

Document stats tracking for analytics

Rate limiting with express-rate-limit

API key generation and validation

Favorites system for saved endpoints

Email & Notifications

Nodemailer integration with SMTP

Email templates for auth, payments, support

Push notification system with DynamoDB storage

WebSocket-based real-time notifications

Email verification for password reset

Notification preferences management

Technical Implementations

Video Processing Pipeline

FFmpeg integration with fluent-ffmpeg wrapper

Quality presets: fast (CRF 28), balanced (CRF 23), high-quality (CRF 18)

Resolution-based compression (720p, 1080p, 1440p, 4k)

Target size reduction (10-90%) with bitrate calculation

Temporary file management with cleanup

Binary response with compression metadata in headers

PDF Conversion System

Puppeteer for HTML-to-PDF with custom page sizes

Ghostscript for PDF-to-Images with DPI control

Mammoth.js for Word document parsing

PDFKit for programmatic PDF generation

Page range selection (all, 1-5, 1,3,5)

Background color and crop options

Image Processing with OpenCV

Python child process spawning for OpenCV operations

Image resize with 4 modes (fit, fill, crop, stretch)

LANCZOS4 interpolation for upscaling

INTER_AREA for downscaling

Format conversion (PNG, JPG, WebP, AVIF)

Quality control with compression parameters

Database Operations

BaseDynamoDBService with CRUD operations

Composite key pattern (provider#email)

Conditional updates with expression attributes

Batch operations for bulk inserts

Query optimization with secondary indexes

Automatic timestamp management (created_at, updated_at)

Security Implementation

Bcrypt password hashing with salt rounds

JWT token signing with HS256 algorithm

Input validation with class-validator

CORS configuration with origin whitelist

Rate limiting per IP address

File upload validation (MIME type, size, extension)

Error Handling & Logging

Global exception filter for consistent error responses

Custom BadRequestException with detailed messages

Try-catch blocks with silent error handling for tracking

Console logging for debugging

Error propagation with proper HTTP status codes

Validation pipe for DTO transformation

Technology Stack

Core Framework

NestJS 11.0.1

TypeScript 5.7.3

Node.js 20.x

Express.js

Database

AWS DynamoDB

@aws-sdk/client-dynamodb 3.864

@aws-sdk/lib-dynamodb 3.864

NoSQL Design

Authentication

JWT (jsonwebtoken 9.0.2)

Bcrypt 5.1.1

Google OAuth 2.0

Custom Guards

Real-time

Socket.io 4.8.1

@nestjs/websockets 11.1.6

@nestjs/platform-socket.io 11.1.6

WebSocket Gateway

File Storage

AWS S3 (@aws-sdk/client-s3 3.864)

Cloudflare R2

Multer 2.0.2

Sharp 0.34.5

Media Processing

FFmpeg (fluent-ffmpeg 2.1.3)

Puppeteer 24.31.0

Sharp 0.34.5

OpenCV4 (Python)

PDF Processing

PDFKit 0.17.1

Mammoth 1.11.0

Ghostscript CLI

Puppeteer 24.31.0

Utilities

Axios 1.11.0

Validator 13.15.15

UUID 10.0.0

Nodemailer 7.0.10

API Layer

Express Rate Limit 7.4.1

Class Validator 0.14.2

Class Transformer 0.5.1

Multer 2.0.2

Scheduling

@nestjs/schedule 6.0.0

Cron Jobs

Billing Reset Service

Usage Aggregation

Testing

Jest 29.7.0

Supertest 7.0.0

ts-jest 29.2.5

E2E Testing

DevOps

ESLint 9.18.0

Prettier 3.4.2

TypeScript ESLint 8.20.0

GitHub Actions

Performance Metrics & Results

50+

API Endpoints

Production-ready

Microservices

Modular architecture

Database Tables

NoSQL design

10+

WebSocket Events

Real-time

60K+

Lines of Code

Solo developer

Jest

Test Coverage

Unit + E2E

Key Takeaways & Learnings

This project demonstrates expertise in building production-ready microservices architecture with NestJS, implementing complex business logic for subscription management, integrating multiple third-party services (AWS, Cashfree, FFmpeg, Puppeteer, OpenCV), and maintaining high code quality with TypeScript strict mode. Key achievements include handling 50+ API endpoints, real-time WebSocket communication, video/image/PDF processing pipelines, and comprehensive API usage tracking.

Technical Skills

NestJS, TypeScript, AWS DynamoDB, Socket.io, FFmpeg, Puppeteer, OpenCV4, JWT, Bcrypt

Best Practices

Microservices, Clean Architecture, Guards, Decorators, Error Handling, Security

Soft Skills

System Design, API Design, Documentation, Performance Optimization