DEV Community: Souvick Sarkar

I Built a Production-Grade Auth API From Scratch — Here's Everything I Learned

Souvick Sarkar — Fri, 31 Jul 2026 10:03:38 +0000

Most tutorials teach you authentication in 15 minutes. They show you jwt.sign(), slap a middleware on a route, and call it a day.

Real authentication systems are nothing like that.

I spent 5 weeks building Swaraksha — a production-grade authentication API that handles everything a real system needs: JWT token pairs, refresh token rotation with theft detection, TOTP-based multi-factor authentication, role-based access control, account lockouts, rate limiting, and a fully automated deployment pipeline.

This article is the deep dive. I will walk you through every feature, every design decision, and every mistake I made along the way.

GitHub: Repo Link
Live Swagger Docs: Demo Link

The Tech Stack
Before we get into the code, here is what I used and why:

Part 1: Authentication That Actually Works

The Problem With Single Tokens
Most tutorials give you one JWT token. The user logs in, gets a token, and uses it for everything. But this creates a horrible tradeoff:

Short-lived token (15 minutes)? The user has to log in again every 15 minutes. Terrible UX.
Long-lived token (7 days)? If someone steals it, they have full access for a week. Terrible security.

The Solution: Token Pairs
Swaraksha uses two tokens:

Access Token (15 minutes) — Used for every API request. Short-lived, so even if stolen, the damage window is tiny.
Refresh Token (7 days) — Stored securely by the client. Used only to get a new access token when the old one expires.

Refresh Token Rotation (Theft Detection)
Here is where it gets interesting. Every time a client uses a refresh token to get a new access token, I immediately invalidate the old refresh token and issue a brand new one.

Why? Imagine this scenario:

A hacker steals your refresh token.
You use your (original) refresh token to get a new access token.
The server gives you a new token pair and marks the old refresh token as "used."
The hacker tries to use the stolen (now "used") refresh token.
The server detects reuse of a consumed token → Token Theft Detected!
The server instantly revokes the ENTIRE token family, logging out both you and the hacker.

This is called Automatic Reuse Detection, and it is the industry standard used by Auth0 and Okta.

Part 2: Multi-Factor Authentication (MFA)
Adding a password is good. Adding a second factor is better.

Swaraksha implements TOTP (Time-Based One-Time Password) — the same protocol used by Google Authenticator and Authy.

How It Works

Setup: The server generates a secret key and returns it as a QR code URI.
Enable: The user scans the QR code in their authenticator app and sends back a 6-digit code to prove it works.
Login: After entering their password, users must provide the current 6-digit code from their authenticator app.

The beauty of TOTP is that the server never needs to send a code to the user. The authenticator app and the server independently generate the same code based on the shared secret and the current time. If they match, the user is verified.

Part 3: Role-Based Access Control (RBAC)
Not every user should have the same power. Swaraksha has three roles:

The authorize Middleware
The key insight is separating authentication (who are you?) from authorization (what are you allowed to do?).

Now protecting a route is a single line:

Part 4: Defensive Programming

Account Lockouts
Brute-force attacks try thousands of passwords per second. To stop them, Swaraksha tracks failed login attempts:

5 failed attempts → Account is locked for 15 minutes.
Every failed attempt increments a counter in the database.
A successful login resets the counter to zero.

Rate Limiting with Upstash Redis
Even with account lockouts, an attacker could target thousands of different accounts. Rate limiting stops this by restricting requests per IP address:

Login routes: 5 requests per 15 minutes per IP
API routes: 100 requests per minute per IP

Zod Validation at the Framework Level

Instead of manually checking if (!email || !password) in every route, Swaraksha uses Zod schemas that Fastify automatically enforces:

Part 5: Containerization with Docker

Why Docker?
"But it works on my machine!" — Every developer, ever.

Docker packages your entire application — Node.js version, dependencies, compiled code — into a single, portable image. It will run identically on your laptop, your teammate's laptop, and a cloud server in Singapore.

Multi-Stage Builds
A naive Dockerfile would install TypeScript, compile the code, and ship everything — including the compiler. That is wasteful and insecure.

Swaraksha uses a multi-stage build:

Part 6: CI/CD — From Push to Production
This is the part that makes everything feel like magic.

The Pipeline
Every time I push code to main, GitHub Actions automatically:

Checks out the code on a fresh Ubuntu server
Installs dependencies and caches node_modules
Runs TypeScript compilation to catch type errors
Runs the entire Vitest test suite to catch logic errors
Builds the Docker image to catch packaging errors
Pushes the image to GitHub Container Registry
SSHs into my DigitalOcean Droplet and pulls the new image
Runs database migrations in a disposable container
Swaps the live container with the new one

The Migration Deadlock
I hit an interesting bug during deployment. My original pipeline was:

Start the container
Wait for it to be running
Run database migrations inside the container

*The problem? *
The Fastify server tried to connect to the database on startup. If the database schema was not migrated yet, the server crashed instantly. I could never reach step 3 because the container died at step 1.

The fix: Run migrations in a temporary, disposable container before starting the real server:

Part 7: Infrastructure & Security

Server Hardening
The DigitalOcean Droplet runs Ubuntu with:

UFW Firewall — Only ports 22 (SSH), 80 (HTTP), and 443 (HTTPS) are open. Port 3000 (Node.js) is blocked from the outside world.

SSH Key Authentication — Password login is disabled. Only cryptographic keys can access the server.

Non-root Docker User — Even if someone exploits the Node.js app, they cannot escalate to root.

Caddy Reverse Proxy
The Node.js server is never directly exposed to the internet. A Caddy reverse proxy sits in front of it:

Internet → Caddy (port 80) → Node.js (port 3000, internal only)

Caddy handles all incoming traffic, protects against malformed requests, and forwards legitimate traffic to the Node.js app over Docker's internal network.

Secrets Management
No secret is ever committed to Git. Environment variables are stored as GitHub Secrets and injected into the server's .env file during deployment by the CI/CD pipeline.

Part 8: Observability
A deployed app without monitoring is a ticking time bomb. Swaraksha includes:

Sentry (Error Tracking)
Every unhandled exception is automatically captured and sent to Sentry with the full stack trace

Health Endpoint
A simple /health endpoint returns the server's uptime and timestamp. Uptime monitoring services (like UptimeRobot) ping this every 5 minutes and email me if the server goes down.

What I Learned

Authentication is never "done." There is always another attack vector to consider — token theft, brute force, replay attacks, timing attacks.

CI/CD is not optional. Manual deployments are error-prone. Automating the pipeline saved me hours and eliminated "it worked on my machine" bugs.

Docker multi-stage builds are essential. Shipping development tools to production is a security risk and a waste of resources.

Database migrations in production are scary The migration deadlock taught me to always migrate before the app starts, never after.

Monitoring is as important as coding. If your server crashes and nobody knows, did it really crash? Yes. Yes it did.

Try It Yourself
GitHub: github.com/SouvickSarkar20/Swaraksha
Live Swagger Docs: http://168.144.117.195/docs

Thanks for reading. If you have questions or spot something I could improve, drop a comment below!

Scaling PostgreSQL without Microservices: Lessons from Notion’s 480 Shards

Souvick Sarkar — Sat, 21 Feb 2026 06:03:51 +0000

I’ve been using Notion to manage my projects for a long time—it’s a faithful friend in my workflow. Recently, while studying database scaling, a thought hit me: How does the "manager" manage itself?

With millions of users reading and writing data every second, the infrastructure behind the scenes must be immense. I decided to dive deep into their architecture, and here is what I learned about the scaling strategy that keeps Notion running.

📝 TL;DR: Scaling Notion’s Monolith

I spent the last few days deconstructing how Notion scaled their PostgreSQL database to handle billions of blocks while keeping their Node.js monolith. Here is the blueprint of what I learned:

Application-Level Sharding: Instead of one massive DB, they use 480 logical shards mapped to a smaller set of physical nodes.

The Shard Router: The logic lives in the TypeScript code, using a simple space_id % 480 math to route requests instantly.

PgBouncer: They use this as a "traffic controller" to pool connections and prevent the database from choking under high load.

Zero-Downtime Migrations: I broke down how they moved billions of rows using a "Shadow Write" strategy to keep the app live during the transition.

The Architecture at a Glance

Chapter 1: The Problem with Monolith

In its early days, Notion followed a simple architecture: a Node.js backend paired with a single PostgreSQL instance. But eventually, they hit the ceiling:

CPU Saturation: Daily spikes were hitting 90%+.

The Vacuum Problem: Autovacuum couldn't keep up, risking a Transaction ID Wraparound—a state where the database stops accepting writes to prevent corruption.

Chapter 2: Why Not Microservices?

The common logic is: Split the code, split the load.
Notion took the opposite approach. They kept the Monolithic backend to maintain operational velocity and data locality (essential for their complex "block" graph) and focused entirely on sharding the Persistence Layer.

Chapter 3: The 480-Shard Blueprint

The "pro move" here was decoupling data from hardware using Logical Shards:

The Key: They used space_id as the Partition Key so all data for one workspace stays together for fast joins.

The Setup: They created 480 independent schemas (Logical Shards) and distributed them across 32 physical AWS RDS instances.

The Result: When a server gets overwhelmed, they just "pick up" a logical schema and move it to a new server. Linear Scalability.

Chapter 4: The Great "Shadow" Migration

How do you move 480 terabytes of data while the plane is mid-flight?

The Backfill: Historical data moved to shards in the background.

Double Writing: Code wrote new changes to both the old DB and new shards simultaneously.

The Cutover: Once a comparison engine verified the data was identical, they flipped the switch.

SOME FUTURE IMPROVEMENTS -

Scaling to 96 Nodes
By 2023, the original 32 servers hit their limit. Because we had 480 Logical Shards, scaling was simple: we tripled capacity to 96 nodes. We didn't change any code; we just redistributed the shards. This is the beauty of Linear Scalability.
It’s Blocks All the Way Down
Why the rapid growth? In Notion, Everything is a Block. A single page is actually a tree of dozens of individual units (text, toggles, images). We aren't just scaling pages; we are managing billions of atomic blocks.
Data Lakes & Connection Hubs
Analytics: To run reports across 480 separate databases, we piped everything into a central Data Lake using tools like Fivetran and Snowflake.
Networking: We used PgBouncer for connection pooling, preventing our backend from choking while trying to talk to hundreds of shards at once.

Wrapping Up
Notion’s journey proves that you don't always need to chase the latest architectural trends. By focusing on the actual bottleneck—the Persistence Layer—they scaled to billions of blocks while keeping their team lean and their code manageable.

I am in the early stages of my engineering journey and would be happy to learn and contribute to more conversations like this.

Do share your thoughts in the comments!