An enterprise-grade, production-ready, full-stack URL shortening and analytics platform engineered with Node.js, Express, MongoDB, Redis, BullMQ, React 19, Vite, and Docker.
flowchart TD
Client["Clients / Browsers / Mobile"] --> Ingress["Reverse Proxy (Nginx / ALB)"]
subgraph Frontend["Presentation Layer"]
Ingress -->|Static Assets :3000| SPA["React 19 + Vite (Nginx Alpine)"]
end
subgraph Backend["Core API Service :5000"]
Ingress -->|API Requests :5000| App["Express 5 REST API"]
App --> Mid1["1. Request ID & Structured Logging (Pino)"]
Mid1 --> Mid2["2. Security (Helmet, CORS, NoSQL Sanitizer, HPP)"]
Mid2 --> Mid3["3. Distributed Rate Limiter (RedisStore)"]
Mid3 --> Router{"Express Router"}
Router -->|/api/health/*| Health["Health Controller (Live / Ready)"]
Router -->|/api/auth/*| Auth["Auth Controller (JWT + Refresh Tokens)"]
Router -->|/api/urls/*| UrlCtrl["URL Management Controller"]
Router -->|/:code| Redir["Redirect Engine (302 Found)"]
end
subgraph Persistence["Storage & Caching Layer"]
Redir -->|1. Cache-Aside Query| RedisCache[("Redis 7.4 Cache")]
Redir -->|2. Buffer Click| RedisBuffer[("Redis Atomic Hash Buffer")]
UrlCtrl -->|CRUD / Indexes| MongoDB[("MongoDB 7.0")]
Auth -->|Users & Tokens| MongoDB
RedisCache -.->|On Cache Miss| MongoDB
end
subgraph Background["Worker & Queue Subsystem"]
Worker["BullMQ Worker Service"] -->|Scheduled Flush| RedisBuffer
Worker -->|Atomic bulkWrite| MongoDB
end
- Modular Monolith Architecture: Strict separation of concerns across Routes, Controllers, Services, Repositories, and Mongoose Models.
- High-Throughput Redirect Engine:
302 Foundnon-permanent redirection preserves real-time click tracking while preventing aggressive browser caching.- Redis Cache-Aside architecture delivers sub-5ms link resolution.
- Single-Flight Cache Stampede Protection: Coalesces concurrent cache misses for the same key into a single MongoDB lookup.
- Asynchronous Click Batching:
- Direct database writes on high-traffic redirects cause write-lock bottlenecks. Clicks are buffered into Redis hashes (
HINCRBY) and flushed asynchronously in batches by a dedicated BullMQ worker viaUrl.bulkWrite().
- Direct database writes on high-traffic redirects cause write-lock bottlenecks. Clicks are buffered into Redis hashes (
- Resilient Dual-Token Authentication:
- Short-lived Access Tokens (15 min) verified statelessly in memory.
- Secure,
HttpOnly,SameSiteRefresh Tokens stored hashed (SHA-256) in MongoDB with Family-Based Rotation & Automatic Theft Reuse Detection.
- Defense-in-Depth Security:
- NoSQL Injection Defense: Recursive query sanitization stripping
$gt,$ne, and$whereoperators. - Prototype Pollution Prevention: Strips
__proto__andconstructorkeys from all JSON payloads. - HTTP Parameter Pollution (HPP): Normalizes duplicated query parameters.
- Content Security Policy & Headers: Powered by Helmet with strict script, frame, and transport directives.
- Custom CSRF Header Validation: Enforces
X-Requested-With: XMLHttpRequestfor all cookie-authenticated state mutations. - Distributed Rate Limiting: Redis-backed sliding-window rate limiting with graceful fallback to memory.
- NoSQL Injection Defense: Recursive query sanitization stripping
- Observability & Health Checks:
- Structured JSON Logging (Pino): High-resolution monotonic timers (
process.hrtime.bigint()) and automated credential/PII redaction. - Kubernetes-Grade Health Probes:
GET /api/health/live: Fast process liveness probe.GET /api/health/ready: Downstream dependency readiness check (MongoDB & Redis active pings with 2s timeouts).GET /api/health: Diagnostic status reporting memory (rssMb,heapUsedMb) and service latency.
- Structured JSON Logging (Pino): High-resolution monotonic timers (
- Graceful Shutdown Coordinator:
- Listens for
SIGTERMandSIGINT. - Fails readiness probes immediately to divert load balancer traffic.
- Drains active keep-alive HTTP sockets, stops BullMQ queue consumers, and gracefully disconnects Redis and MongoDB pools with a 10s watchdog fallback.
- Listens for
- Containerization & Orchestration:
- Multi-stage Docker builds utilizing lightweight Alpine/Slim images and non-root users (
USER node). docker-compose.ymlorchestrating 5 isolated services:mongo,redis,api,worker, andclient.
- Multi-stage Docker builds utilizing lightweight Alpine/Slim images and non-root users (
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| Runtime | Node.js | v22 LTS | Fast, modern asynchronous JavaScript execution |
| Framework | Express | v5.2 | Web framework with native async error handling |
| Database | MongoDB | v7.0 | Primary document datastore with compound indexes |
| ODM | Mongoose | v9.1 | Schema modeling, validation, and middleware |
| Cache & Queue | Redis & BullMQ | v7.4 / v6.7 | In-memory cache-aside, click buffering, and worker queues |
| Logging | Pino | v10.4 | Ultra-low overhead structured NDJSON logging |
| Security | Helmet, bcrypt, rate-limit-redis | Latest | Headers, password hashing, distributed throttling |
| Frontend | React, Vite, Nginx | v19 / Alpine | Reactive dashboard served via reverse proxy |
| Testing | Node Test Runner (node:test) |
Built-in | Fast, zero-dependency unit, integration, and E2E tests |
URL-SHORTNER-FULLSTACK/
├── client/ # Frontend Single Page Application
│ ├── src/ # React components, pages, hooks, API client
│ ├── nginx.conf # SPA routing, gzip, and security headers
│ ├── Dockerfile # Multi-stage build (Vite build -> Nginx Alpine)
│ └── package.json
├── server/ # Backend API & Worker Service
│ ├── config/ # Environment validation, logger, DB, Redis config
│ ├── controllers/ # Request handlers & response formatting
│ ├── middleware/ # Rate limiters, sanitize, HPP, auth, logging
│ ├── models/ # Mongoose schemas (User, Url, RefreshToken)
│ ├── routes/ # Express route definitions
│ ├── services/ # Core business logic (auth, url, cache, jobs)
│ ├── jobs/ # BullMQ queue processors and schedulers
│ ├── utils/ # Cryptography, tokens, errors, graceful shutdown
│ ├── validators/ # Request payload schemas
│ ├── tests/ # 127 automated unit, integration, and E2E tests
│ ├── Dockerfile # Node 22 slim image with dumb-init & non-root user
│ ├── app.js # Express app setup and middleware pipeline
│ ├── server.js # HTTP server entry point with shutdown handler
│ └── worker.js # Standalone queue worker entrypoint
├── docker-compose.yml # Full multi-container orchestration (5 services)
├── ARCHITECTURE_AUDIT.md # Initial legacy codebase audit & roadmap
├── ARCHITECTURE.md # Deep-dive system architecture specification
└── README.md # Platform documentation & operational runbook
To launch the complete platform (Database, Cache, API, Queue Worker, and Frontend) in production-ready containers:
docker compose up --build -dVerify the stack health:
docker compose psAccess the services:
- Frontend UI: http://localhost:3000
- REST API & Health: http://localhost:5000/api/health
- MongoDB:
localhost:27017 - Redis:
localhost:6379
To view consolidated structured logs:
docker compose logs -f api workerTo stop the containers gracefully:
docker compose down- Node.js 20+ installed
- MongoDB and Redis running locally (or via Docker)
cd server
npm install
npm run devcd server
npm run workercd client
npm install
npm run devCreate a .env file in server/ (or configure in docker-compose.yml):
| Variable | Type | Default | Description |
|---|---|---|---|
PORT |
Number | 5000 |
Port for the Express HTTP server |
NODE_ENV |
String | development |
Environment mode (development, production, test) |
MONGO_URI |
String | Required | MongoDB connection URI (mongodb://localhost:27017/url-shortener) |
REDIS_URL |
String | Optional | Redis connection URL (redis://localhost:6379). If omitted, caching is gracefully disabled |
BASE_URL |
String | http://localhost:5000 |
Fully-qualified public domain prefix for generated short links |
CLIENT_URL |
String | http://localhost:3000 |
Allowed CORS origin for frontend single page application |
JWT_SECRET |
String | Required | Secret key for signing Access Tokens (minimum 32 characters) |
ACCESS_TOKEN_EXPIRES_IN |
String | 15m |
Lifetime of stateless Access Tokens |
REFRESH_TOKEN_DAYS |
Number | 30 |
Expiration window for refresh tokens in days |
CACHE_TTL_SECONDS |
Number | 300 |
Redis link cache TTL in seconds (5 minutes) |
CLICK_FLUSH_INTERVAL_SECONDS |
Number | 10 |
Frequency in seconds at which buffered clicks flush to MongoDB |
JOBS_MODE |
String | inline |
inline (run jobs inside server process) or off (run in dedicated worker process) |
TRUST_PROXY |
Number/Bool | 1 |
Reverse proxy hop count for accurate IP extraction |
GET /api/health/live: Fast process liveness probe. Returns200 OK.GET /api/health/ready: Dependency readiness probe. Returns200 OKwhen MongoDB is connected;503 Service Unavailablewhen downstream dependencies fail.GET /api/health: Diagnostic report containing system uptime, memory allocation, and database latencies.
POST /api/auth/register: Register account (name,email,password). Returns access token and setsrefreshTokencookie.POST /api/auth/login: Authenticate credentials (email,password). Returns access token and setsrefreshTokencookie.GET /api/auth/me: Fetch authenticated user profile (Authorization: Bearer <token>).POST /api/auth/refresh: Rotate refresh token and obtain a new access token (RequiresCookieandX-Requested-With: XMLHttpRequest).POST /api/auth/logout: Revoke active session and clear cookie.POST /api/auth/logout-all: Invalidate all active user sessions globally by incrementingtokenVersion.
POST /api/urls: Create a shortened URL. AcceptsoriginalUrl, optionalcustomCode, and optionalexpiresAt.GET /api/urls: List user's links with pagination (?page=1&limit=10&sort=createdAt&order=desc&search=term).GET /api/urls/:id: Retrieve details and metrics for an individual link.PATCH /api/urls/:id: Update destination URL, expiration date, or status (active/disabled). Automatically purges Redis cache.DELETE /api/urls/:id: Soft-delete short link (status: "deleted"). Immediately renders code410 Gone.
GET /:code: Public resolution endpoint.- Returns
302 Foundwith target inLocationheader. - Sets
Cache-Control: no-store, no-cache, must-revalidate. - Automatically records visitor analytics and buffers click increments.
- Returns
410 Goneif expired or deleted; returns404 Not Foundif nonexistent.
- Returns
The platform includes 127 automated tests executed via the native Node.js test runner (node:test):
npm --prefix server testTest coverage includes:
- Unit Validation: Schemas, custom code rules, regex sanitization, reserved word blacklists.
- Security Tests: NoSQL injection operator stripping, prototype pollution resistance, HPP prevention, payload size limits.
- Database & Cache: Compound index explain plans, cache-aside populate/invalidate, stampede coalescing.
- Background Jobs: Atomic Redis hash click buffering, BullMQ schedulers, bulk write updates.
- Graceful Teardown: Signal trapping (
SIGTERM/SIGINT), readiness probe draining, socket teardown. - End-to-End User Flow: Full HTTP integration from registration, authentication, link creation, redirection, updating, token refreshing, to deletion.
- Generate a cryptographically secure
JWT_SECRET($\ge 32$ characters). - Set
NODE_ENV=production. - Set
COOKIE_SECURE=true(requires HTTPS). - Configure
JOBS_MODE=offin API containers, and runworker.jsin a dedicated container. - Set
TRUST_PROXY=1(or your load balancer hop count) to ensure accurate client IP rate limiting.
This project is licensed under the ISC License.