Search "design a chat system" and you'll find hundreds of articles. Most of them give you a box labeled "Chat Server" with some arrows pointing at a database and call it a day.

That's not a design. That's a diagram with no decisions in it.

The real challenge in designing a chat system isn't the happy path — it's everything that goes wrong. What happens when a user goes offline mid-message? How do you guarantee a message sent to a group of 500 people actually reaches all of them? What does "delivered" even mean at scale?

This post covers the full architecture for a WhatsApp-style chat system supporting 1-on-1 and group messaging — with real decisions, real tradeoffs, and the three technical problems that will define your design: WebSockets, message delivery guarantees, and scaling to millions of concurrent users.

Requirements

Before touching architecture, let's be precise about what we're building.

Functional requirements:

• 1-on-1 messaging between users

• Group messaging (up to 500 members per group)

• Message delivery receipts (sent, delivered, read)

• Online/offline presence indicators

• Message history persistence

• Media sharing (images, files) — basic support

Non-functional requirements:

• Low latency — messages should feel real-time (under 100ms end-to-end)

• High availability — 99.99% uptime, chat can't go down

• At-least-once delivery — no message ever silently lost

• Eventual consistency — slight delay in delivery receipts is acceptable

• Scale — 50 million daily active users, 100 messages per user per day = 5 billion messages per day

Let's use these constraints to drive every architectural decision.

The Naive Approach (And Why It Fails)

The obvious first attempt:

User A → HTTP POST /messages → Server → Database → Poll for new messages → User B

User B polls every few seconds asking "any new messages?" This works for email. It's catastrophic for chat.

At 50M users polling every 3 seconds:

• 16.6 million requests per second — just for polling

• Most responses are empty — wasted compute

• Minimum latency is your polling interval — 3 seconds feels broken for chat

You need persistent connections. Enter WebSockets.

Part 1: WebSockets — The Foundation of Real-Time Messaging

How WebSockets Work

HTTP is request-response — the client always initiates. WebSockets upgrade an HTTP connection to a persistent, bidirectional channel. Once established, either side can send data at any time.

Client                          Server
  │                               │
  │── HTTP GET /chat ──────────►  │
  │   Upgrade: websocket          │
  │◄─ 101 Switching Protocols ──  │
  │                               │
  │  ◄──── persistent connection ────►  │
  │                               │
  │◄── {"type":"message",...} ──  │  (server pushes)
  │── {"type":"ack",...} ────────►│  (client responds)

The connection lifecycle:

# FastAPI WebSocket endpoint
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
from typing import Dict
import json

app = FastAPI()

class ConnectionManager:
    def __init__(self):
        # user_id → WebSocket connection
        self.active_connections: Dict[str, WebSocket] = {}

    async def connect(self, user_id: str, websocket: WebSocket):
        await websocket.accept()
        self.active_connections[user_id] = websocket
        await self.update_presence(user_id, online=True)

    async def disconnect(self, user_id: str):
        self.active_connections.pop(user_id, None)
        await self.update_presence(user_id, online=False)

    async def send_to_user(self, user_id: str, message: dict) -> bool:
        websocket = self.active_connections.get(user_id)
        if websocket:
            await websocket.send_json(message)
            return True
        return False  # User offline — message needs queuing

    async def update_presence(self, user_id: str, online: bool):
        # Publish to Redis pub/sub so other servers know
        await redis.publish(
            f"presence:{user_id}",
            json.dumps({"user_id": user_id, "online": online})
        )

manager = ConnectionManager()

@app.websocket("/ws/{user_id}")
async def websocket_endpoint(websocket: WebSocket, user_id: str):
    await manager.connect(user_id, websocket)
    try:
        while True:
            data = await websocket.receive_json()
            await handle_message(user_id, data)
    except WebSocketDisconnect:
        await manager.disconnect(user_id)

The Problem With WebSockets at Scale

A single server can maintain roughly 65,000 concurrent WebSocket connections (limited by OS file descriptors). At 50M DAU with 20% concurrently online, that's 10M concurrent connections — requiring 153+ chat servers just to hold connections.

This creates the core architectural challenge: User A's connection is on Server 1. User B's connection is on Server 7. How does a message from A reach B?

The answer is a message broker acting as the backbone between servers.

The Architecture

Here's the full system:

                    ┌─────────────────────────────┐
                    │         Clients              │
                    │   (WebSocket connections)    │
                    └──────────┬──────────────────┘
                               │
                    ┌──────────▼──────────────────┐
                    │      Load Balancer           │
                    │  (sticky sessions by user)   │
                    └──────────┬──────────────────┘
                               │
          ┌────────────────────┼────────────────────┐
          │                    │                    │
   ┌──────▼──────┐    ┌────────▼──────┐    ┌───────▼──────┐
   │  Chat Server│    │  Chat Server  │    │  Chat Server  │
   │     #1      │    │     #2        │    │     #3        │
   └──────┬──────┘    └──────┬────────┘    └──────┬───────┘
          │                  │                    │
          └──────────────────┼────────────────────┘
                             │
                    ┌────────▼────────────┐
                    │   Message Broker    │
                    │  (Kafka / SQS)      │
                    └────────┬────────────┘
                             │
          ┌──────────────────┼────────────────────┐
          │                  │                    │
   ┌──────▼──────┐    ┌──────▼──────┐    ┌───────▼──────┐
   │  Message    │    │   Presence  │    │  Push Notif  │
   │  Storage    │    │   Service   │    │  Service     │
   │ (DynamoDB)  │    │  (Redis)    │    │ (APNs/FCM)   │
   └─────────────┘    └─────────────┘    └──────────────┘

Component Responsibilities

Load Balancer — Sticky Sessions

Route each user to the same chat server for the duration of their session. This keeps WebSocket connections stable and avoids re-routing overhead. Use consistent hashing on user_id.

Chat Servers — Connection Holders

Each chat server does three things:

1. Maintains WebSocket connections for its assigned users

2. Receives incoming messages and publishes to the message broker

3. Subscribes to the message broker and delivers messages to connected users

Message Broker (Kafka)

The backbone. Every message flows through Kafka, which provides:

• Guaranteed delivery between chat servers

• Replay capability for debugging

• Fan-out for group messages

• Decoupling of send and receive paths

Message Storage (DynamoDB)

Persistent message history. DynamoDB's access pattern fits perfectly — you almost always query by conversation_id to get recent messages.

Presence Service (Redis)

Tracks who is online. Redis pub/sub broadcasts presence changes to all interested servers in real time.

Push Notification Service

When a recipient is offline, route to APNs (iOS) or FCM (Android) instead of a WebSocket.

Part 2: Message Delivery Guarantees — The Hard Part

This is where most system design discussions stop too early. Let's go deeper.

The Three Guarantees

At-most-once: Message is sent once. If delivery fails, it's not retried. Messages can be lost. Never acceptable for chat.

At-least-once: Message is retried until acknowledged. Messages might be delivered multiple times (duplicates). Acceptable if you handle deduplication.

Exactly-once: Message is delivered precisely once, no duplicates, no losses. Theoretically ideal. In practice, extremely hard to implement correctly across distributed systems.

For chat systems: target at-least-once delivery with client-side deduplication.

The Message Flow With Delivery Guarantees

1. Sender assigns a client-generated idempotency key (UUID)
2. Message sent to Chat Server
3. Chat Server persists to DynamoDB (idempotency key as sort key)
4. Chat Server publishes to Kafka
5. Chat Server returns ACK to sender → sender marks as "sent" ✓
6. Kafka consumer delivers to recipient's Chat Server
7. Recipient's Chat Server delivers via WebSocket
8. Recipient's client sends ACK
9. Chat Server publishes delivery receipt to Kafka
10. Sender's Chat Server receives receipt → sender marks "delivered" ✓
11. Recipient opens conversation → "read" receipt sent
12. Sender marks "read" ✓

The idempotency key is critical. If step 3 succeeds but the server crashes before step 5, the sender will retry. Without an idempotency key, you get duplicate messages. With it, the database insert is a no-op on retry.

import uuid
from datetime import datetime

class Message:
    def __init__(
        self,
        sender_id: str,
        conversation_id: str,
        content: str,
        idempotency_key: str = None
    ):
        self.message_id = str(uuid.uuid4())
        self.idempotency_key = idempotency_key or str(uuid.uuid4())
        self.sender_id = sender_id
        self.conversation_id = conversation_id
        self.content = content
        self.timestamp = datetime.utcnow().isoformat()
        self.status = "sent"

async def send_message(message: Message) -> dict:
    # Idempotent write — if key exists, return existing record
    try:
        await dynamodb.put_item(
            TableName="messages",
            Item={
                "conversation_id": {"S": message.conversation_id},
                "message_id": {"S": message.message_id},
                "idempotency_key": {"S": message.idempotency_key},
                "sender_id": {"S": message.sender_id},
                "content": {"S": message.content},
                "timestamp": {"S": message.timestamp},
                "status": {"S": "sent"}
            },
            ConditionExpression="attribute_not_exists(idempotency_key)"
        )
    except dynamodb.exceptions.ConditionalCheckFailedException:
        # Already saved — idempotent, return success
        pass

    # Publish to Kafka regardless (Kafka consumer handles dedup)
    await kafka_producer.send(
        topic="messages",
        key=message.conversation_id.encode(),
        value=message.__dict__
    )

    return {"status": "sent", "message_id": message.message_id}

Handling Offline Users

When a recipient is offline, the message must not be lost. The flow changes:

async def deliver_message(message: dict, recipient_id: str):
    # Try WebSocket first
    delivered = await manager.send_to_user(recipient_id, message)

    if not delivered:
        # User offline — store in their message queue
        await dynamodb.put_item(
            TableName="offline_queue",
            Item={
                "user_id": {"S": recipient_id},
                "timestamp": {"S": message["timestamp"]},
                "message_id": {"S": message["message_id"]},
                "message": {"S": json.dumps(message)}
            }
        )
        # Send push notification
        await push_service.notify(
            user_id=recipient_id,
            title=f"New message from {message['sender_id']}",
            body=message["content"][:100]
        )

async def on_user_connect(user_id: str):
    # Drain offline queue on reconnect
    queued = await dynamodb.query(
        TableName="offline_queue",
        KeyConditionExpression="user_id = :uid",
        ExpressionAttributeValues={":uid": {"S": user_id}},
        ScanIndexForward=True  # oldest first
    )

    for item in queued["Items"]:
        message = json.loads(item["message"]["S"])
        await manager.send_to_user(user_id, message)

    # Clear the queue
    for item in queued["Items"]:
        await dynamodb.delete_item(
            TableName="offline_queue",
            Key={
                "user_id": {"S": user_id},
                "timestamp": {"S": item["timestamp"]["S"]}
            }
        )

Part 3: Group Messaging — The Fan-Out Problem

1-on-1 messaging is a solved problem at this point. Group messaging is where things get genuinely hard.

The Fan-Out Challenge

When User A sends a message to a group of 500 people:

• 500 delivery operations need to happen

• Members are spread across many chat servers

• Some members are offline

• Some members have the conversation muted

• The operation needs to be fast from A's perspective

Two approaches:

Fan-out on write: When a message is sent, immediately write it to every member's inbox. Each member pulls from their own inbox.

Pros: Fast reads — inbox is pre-computed
Cons: Expensive writes — 500 writes per message
     Wasteful for large groups with many inactive members

Fan-out on read: Store the message once. When a member opens the conversation, compute their view.

Pros: Single write per message, storage efficient
Cons: Expensive reads — compute on every open
     Slower first load for large groups

Hybrid approach (what WhatsApp actually uses):

• For small groups (< 100 members): fan-out on write — fast delivery to active members

• For large groups (100-500 members): store once, use Kafka partitions per group, let each member's server pull

SMALL_GROUP_THRESHOLD = 100

async def handle_group_message(message: Message, group_id: str):
    # Get group members
    members = await get_group_members(group_id)

    if len(members) <= SMALL_GROUP_THRESHOLD:
        # Fan-out on write — direct delivery
        await fan_out_write(message, members)
    else:
        # Store once, publish to group topic
        await store_message(message)
        await kafka_producer.send(
            topic=f"group.{group_id}",
            value=message.__dict__
        )

async def fan_out_write(message: Message, members: list):
    # Publish one Kafka event per member
    tasks = [
        kafka_producer.send(
            topic=f"user.{member_id}",
            value=message.__dict__
        )
        for member_id in members
        if member_id != message.sender_id
    ]
    await asyncio.gather(*tasks)

Group Delivery Receipts — Don't Do What iMessage Does

Showing individual read receipts for every member in a 500-person group is a scaling nightmare — 500 receipt events per message read.

Practical approach:

• Store receipts as a bitmap or counter, not individual records

• Show "Delivered to N members" rather than individual names

• Only compute individual receipts for groups under 20 members

async def update_group_receipt(
    message_id: str,
    group_id: str,
    user_id: str,
    receipt_type: str  # "delivered" or "read"
):
    # Atomic increment — no race conditions
    await dynamodb.update_item(
        TableName="group_receipts",
        Key={
            "message_id": {"S": message_id},
            "group_id": {"S": group_id}
        },
        UpdateExpression=f"ADD {receipt_type}_count :inc",
        ExpressionAttributeValues={":inc": {"N": "1"}}
    )

DynamoDB Schema

The access patterns for chat are simple but the schema design matters enormously for cost and performance.

Table: messages
├── PK: conversation_id (String)     ← partition by conversation
├── SK: timestamp#message_id (String) ← sort by time, unique
├── sender_id (String)
├── content (String)
├── message_type (String)            ← text, image, video
├── status (String)                  ← sent, delivered, read
└── idempotency_key (String)

GSI: sender_id-timestamp-index
├── PK: sender_id
└── SK: timestamp
(For "messages sent by user" queries)

Table: conversations
├── PK: user_id (String)
├── SK: last_message_timestamp (String)
├── conversation_id (String)
├── participant_ids (List)
└── unread_count (Number)

Table: offline_queue
├── PK: user_id (String)
└── SK: timestamp (String)

Key design decisions:

• Partition by conversation_id not user_id — conversations are the natural unit of access

• Use composite sort key timestamp#message_id — enables time-range queries and guarantees uniqueness even for messages sent at the same millisecond

• TTL on offline_queue — auto-expire after 30 days so storage doesn't grow unbounded

Presence System

Real-time online/offline indicators are deceptively complex at scale.

The naive approach: Query the database for last-seen timestamp on every profile view. At scale, this creates a read hotspot.

Better approach: Redis with TTL + pub/sub

PRESENCE_TTL = 60  # seconds

async def heartbeat(user_id: str):
    # Client sends heartbeat every 30 seconds
    # Server refreshes TTL — if it expires, user is offline
    await redis.setex(
        f"presence:{user_id}",
        PRESENCE_TTL,
        "online"
    )

async def is_online(user_id: str) -> bool:
    return await redis.exists(f"presence:{user_id}") == 1

async def subscribe_to_presence(user_ids: list, callback):
    # Subscribe to presence changes for a list of users
    # Used to update UI in real time when contacts go online/offline
    pubsub = redis.pubsub()
    channels = [f"presence:{uid}" for uid in user_ids]
    await pubsub.subscribe(*channels)

    async for message in pubsub.listen():
        if message["type"] == "message":
            await callback(json.loads(message["data"]))

Presence at scale consideration: Don't broadcast presence to all followers. WhatsApp only shows presence to mutual contacts — and even then, only when the user opens a conversation. This limits the fan-out to manageable levels.

Scaling to Millions of Users

The Numbers

Horizontal Scaling Plan

Chat servers: Stateless except for active WebSocket connections. Scale horizontally — add servers as concurrent connections grow. Target: 50,000 connections per server = 200 servers at peak.

Kafka: Partition by conversation_id. This ensures all messages in a conversation are ordered and processed by the same consumer. Use 1,000 partitions — allows scaling to 1,000 parallel consumers.

DynamoDB: Serverless — scales automatically. At 174,000 writes/second, provision ~200,000 WCU with auto-scaling. Cost at this scale: ~$35,000/month. Optimise with DynamoDB Accelerator (DAX) for read-heavy workloads like message history.

Redis (Presence): Use Redis Cluster. Shard by user_id. At 10M concurrent users, each key is ~100 bytes = ~1GB total — fits comfortably in a 3-node Redis cluster.

Geographic Distribution

For a global user base, co-locate users with the closest region:

User in Singapore → AP-Southeast Chat Servers → AP Kafka Cluster
User in London    → EU-West Chat Servers    → EU Kafka Cluster

Cross-region messages:
AP Kafka → Cross-region replication → EU Kafka → EU Chat Server → User

Use AWS Global Accelerator to route users to the nearest chat server cluster. Accept ~50ms cross-region latency for international messages — it's acceptable and much cheaper than a single global cluster.

Media Sharing — The Bandwidth Problem

Never send media through the chat server. It'll saturate your WebSocket connections.

The right approach:

1. Client requests a pre-signed S3 URL from the media service
2. Client uploads directly to S3 (bypasses chat server entirely)
3. Client sends a message containing the S3 object key
4. Recipient's client downloads directly from CloudFront (CDN)

import boto3
from botocore.config import Config

s3 = boto3.client(
    's3',
    config=Config(signature_version='s3v4')
)

async def get_upload_url(
    user_id: str,
    file_type: str,
    file_size_bytes: int
) -> dict:
    # Validate file size (50MB limit)
    if file_size_bytes > 50 * 1024 * 1024:
        raise ValueError("File too large")

    object_key = f"media/{user_id}/{uuid.uuid4()}"

    presigned_url = s3.generate_presigned_url(
        'put_object',
        Params={
            'Bucket': 'chat-media-bucket',
            'Key': object_key,
            'ContentType': file_type,
            'ContentLength': file_size_bytes
        },
        ExpiresIn=300  # 5 minutes to complete upload
    )

    return {
        "upload_url": presigned_url,
        "object_key": object_key,
        "cdn_url": f"https://cdn.yourdomain.com/{object_key}"
    }

This keeps your chat servers lean — they only handle small JSON payloads, never binary data.

What I'd Skip in V1

Not everything needs to be built on day one:

• End-to-end encryption — Signal Protocol is complex. Add it in V2 once the core is stable.

• Voice and video calls — WebRTC is a separate system entirely. Separate service, separate team.

• Message reactions — Nice to have. A simple DynamoDB list attribute works until you have emoji reaction analytics requirements.

• Message editing and deletion — Soft delete first (mark as deleted), hard delete later when compliance requirements are clear.

• Multi-device sync — Start with single-device. Multi-device sync (like WhatsApp Web) is a significant engineering effort involving device registration and message fan-out to device sets.

Key Takeaways

1. WebSockets are necessary but not sufficient — you also need a message broker between servers to route messages across your fleet

2. Target at-least-once delivery with client-side deduplication — exactly-once is theoretically appealing but practically expensive

3. Idempotency keys are non-negotiable — retries without them create duplicate messages

4. Fan-out strategy depends on group size — write fan-out for small groups, read fan-out for large ones

5. Never route media through chat servers — S3 pre-signed URLs + CloudFront keep your servers fast

6. Presence is a separate problem — Redis TTL + pub/sub, not a database column

7. Partition Kafka by conversation_id — preserves message ordering within a conversation

8. DynamoDB partition key is conversation, not user — conversations are the natural unit of access in chat

What Would You Design Differently?

Every chat system has its own constraints. Some teams prioritise encryption above all else. Others need to support 10,000-member broadcast channels. Some operate in regions where push notifications are unreliable.

What's the trickiest chat-related engineering problem you've encountered? Drop it in the comments — I read every one.

Follow me on LinkedIn for weekly posts on system design, AWS, and engineering career growth.

Search "rate limiter system design" and you'll find two kinds of articles.

The first kind gives you a surface-level overview of algorithms with no real implementation details. The second gives you a Redis snippet with no explanation of why that algorithm was chosen, what its failure modes are, or how it behaves under traffic spikes.

Neither prepares you for the real question — which algorithm do you actually use, and when?

This post covers all four major rate-limiting algorithms, compares them honestly, and shows you how to implement per-user and per-IP limiting in a distributed system. By the end, you'll have a decision framework you can apply to any project — not just a definition to recite in an interview.

What Is Rate Limiting and Why Does It Matter?

Rate limiting controls how many requests a client can make to your system in a given time window.

Without it:

• A single misbehaving client can exhaust your server resources

• A credential stuffing attack tries thousands of passwords per second

• A DDoS amplification attack overwhelms your upstream services

• One heavy API consumer degrades the experience for everyone else

Rate limiting protects your system at the edge — before expensive business logic runs.

The Four Algorithms

1. Fixed Window Counter

How it works:

Divide time into fixed windows (e.g., every 60 seconds). Count requests per client per window. Reject once the count exceeds the limit.

Window: 12:00:00 → 12:01:00  |  Limit: 100 requests
 
Client A: ████████████████ 87 requests  ✅
Client B: ████████████████████████ 100 requests  ✅ (101st rejected)

Implementation (Python + Redis):

import redis
import time
 
r = redis.Redis()
 
def is_allowed_fixed_window(client_id: str, limit: int, window_seconds: int) -> bool:
    window_key = int(time.time() // window_seconds)
    key = f"rate:{client_id}:{window_key}"
    
    count = r.incr(key)
    if count == 1:
        r.expire(key, window_seconds)
    
    return count <= limit

Pros:

• Dead simple to implement

• Very low memory — one counter per client per window

• Easy to reason about and debug

Cons — the boundary problem:

This is the critical flaw. A client can make 100 requests at 12:00:59 and another 100 at 12:01:01 — 200 requests in 2 seconds, both within their respective windows but double the intended limit.

Window 1 ends ──────────────────┐
                                 │
                  100 requests ──┘└── 100 requests
                                 │
Window 2 starts ─────────────────┘
 
200 requests in ~2 seconds. Window boundary exploited.

When to use it: Internal admin tools, low-stakes APIs, anywhere simplicity matters more than precision.

2. Sliding Window Counter

How it works:

A refinement of Fixed Window that weights the previous window's count based on how far through the current window you are.

Current count = 
  (previous_window_count × overlap_ratio) + current_window_count

Example:

You're 25% through the current window. Previous window had 80 requests. Current window has 30 so far.

Weighted count = (80 × 0.75) + 30 = 60 + 30 = 90

Implementation:

def is_allowed_sliding_window(client_id: str, limit: int, window_seconds: int) -> bool:
    now = time.time()
    current_window = int(now // window_seconds)
    previous_window = current_window - 1
    
    # How far through the current window are we?
    elapsed = now % window_seconds
    overlap_ratio = 1 - (elapsed / window_seconds)
    
    current_key = f"rate:{client_id}:{current_window}"
    previous_key = f"rate:{client_id}:{previous_window}"
    
    current_count = int(r.get(current_key) or 0)
    previous_count = int(r.get(previous_key) or 0)
    
    weighted_count = (previous_count * overlap_ratio) + current_count
    
    if weighted_count >= limit:
        return False
    
    count = r.incr(current_key)
    if count == 1:
        r.expire(current_key, window_seconds * 2)
    
    return True

Pros:

• Solves the boundary burst problem

• Still memory-efficient — just two counters per client

• Good approximation of true sliding window behaviour

Cons:

• The weighting is an approximation — not perfectly accurate

• Slightly harder to implement correctly

• Edge cases around window boundaries need care

When to use it: Public APIs where you want fairness without the complexity of a full sliding window log.

3. Token Bucket

How it works:

Each client has a bucket that holds tokens. Tokens refill at a constant rate up to a maximum capacity. Each request consumes one token. No token = request rejected.

Bucket capacity: 10 tokens
Refill rate: 2 tokens/second
 
t=0:  [██████████] 10 tokens
t=1:  Request → [█████████ ] 9 tokens
t=1:  Request → [████████  ] 8 tokens
t=2:  Refill  → [██████████] 10 tokens (capped at max)

Implementation:

import time
 
def is_allowed_token_bucket(
    client_id: str,
    capacity: int,
    refill_rate: float  # tokens per second
) -> bool:
    key = f"token_bucket:{client_id}"
    now = time.time()
    
    # Lua script for atomic read-modify-write
    lua_script = """
    local key = KEYS[1]
    local capacity = tonumber(ARGV[1])
    local refill_rate = tonumber(ARGV[2])
    local now = tonumber(ARGV[3])
    
    local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
    local tokens = tonumber(bucket[1]) or capacity
    local last_refill = tonumber(bucket[2]) or now
    
    -- Add tokens based on time elapsed
    local elapsed = now - last_refill
    tokens = math.min(capacity, tokens + elapsed * refill_rate)
    
    if tokens < 1 then
        return 0  -- Rejected
    end
    
    tokens = tokens - 1
    redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
    redis.call('EXPIRE', key, 3600)
    return 1  -- Allowed
    """
    
    result = r.eval(lua_script, 1, key, capacity, refill_rate, now)
    return result == 1

Why Lua? Redis executes Lua scripts atomically — essential here to prevent race conditions where two concurrent requests both read the same token count and both think they can proceed.

Pros:

• Handles bursts naturally — a client can use saved-up tokens for a short burst

• Smooth traffic shaping

• Widely used in production (AWS API Gateway uses token bucket internally)

Cons:

• Two parameters to tune (capacity + refill rate) — easy to misconfigure

• Slightly more complex implementation

• Burst behaviour can be surprising if you're not expecting it

When to use it: APIs where some bursting is acceptable — e.g. a user uploading a batch of files. The token bucket lets them burst briefly without being punished for it.

4. Leaky Bucket

How it works:

Requests enter a queue (the bucket). They're processed at a constant rate regardless of how fast they arrive. If the queue is full, new requests are rejected.

Incoming requests (variable rate)
         │││││││││
         ▼▼▼▼▼▼▼▼▼
    ┌─────────────┐
    │  Queue      │ ← Max capacity: 10
    │  ▓▓▓▓▓▓▓   │
    └──────┬──────┘
           │ constant outflow
           ▼▼▼▼▼▼▼▼  (e.g. 5 req/sec)

Implementation:

def is_allowed_leaky_bucket(
    client_id: str,
    capacity: int,
    leak_rate: float  # requests per second
) -> bool:
    key = f"leaky:{client_id}"
    now = time.time()
    
    lua_script = """
    local key = KEYS[1]
    local capacity = tonumber(ARGV[1])
    local leak_rate = tonumber(ARGV[2])
    local now = tonumber(ARGV[3])
    
    local bucket = redis.call('HMGET', key, 'queue_size', 'last_leak')
    local queue_size = tonumber(bucket[1]) or 0
    local last_leak = tonumber(bucket[2]) or now
    
    -- Drain the bucket based on elapsed time
    local elapsed = now - last_leak
    local leaked = math.floor(elapsed * leak_rate)
    queue_size = math.max(0, queue_size - leaked)
    
    if queue_size >= capacity then
        return 0  -- Bucket full, reject
    end
    
    queue_size = queue_size + 1
    redis.call('HMSET', key, 'queue_size', queue_size, 'last_leak', now)
    redis.call('EXPIRE', key, 3600)
    return 1  -- Allowed
    """
    
    result = r.eval(lua_script, 1, key, capacity, leak_rate, now)
    return result == 1

Pros:

• Guarantees a perfectly smooth, consistent outflow rate

• Protects downstream services from any burst whatsoever

• Predictable processing rate

Cons:

• Bursts are always rejected — even legitimate ones

• Queue management adds latency

• Less intuitive than token bucket

When to use it: Protecting downstream services that can't handle any variation in request rate — payment processors, third-party APIs with strict rate limits, legacy systems with fixed throughput.

Algorithm Comparison

Per-User vs Per-IP Limiting

This is where most tutorials stop. Real systems need both.

The Problem With IP-Only Limiting

• Users behind corporate NAT share one IP — limit one, limit all

• IPv6 makes IP-based blocking trivial to bypass (rotate addresses)

• Mobile users switch IPs constantly

The Problem With User-Only Limiting

• Unauthenticated endpoints can't use user IDs

• Login endpoints need IP limiting before a user ID is even known

• Credential stuffing attacks rotate user accounts

The Solution: Layered Limiting

Apply both, with different limits and algorithms for each layer:

from fastapi import FastAPI, Request, HTTPException
from typing import Optional
 
app = FastAPI()
 
# Layer 1: IP-based (protects unauthenticated endpoints)
IP_LIMIT = 200        # requests per minute per IP
IP_WINDOW = 60
 
# Layer 2: User-based (protects authenticated endpoints)
USER_LIMIT = 100      # requests per minute per user
USER_WINDOW = 60
 
# Layer 3: Endpoint-specific (protects sensitive endpoints)
LOGIN_LIMIT = 5       # login attempts per minute per IP
LOGIN_WINDOW = 60
 
def get_client_ip(request: Request) -> str:
    # Respect X-Forwarded-For if behind a load balancer
    forwarded_for = request.headers.get("X-Forwarded-For")
    if forwarded_for:
        return forwarded_for.split(",")[0].strip()
    return request.client.host
 
async def rate_limit_middleware(
    request: Request,
    user_id: Optional[str] = None
):
    client_ip = get_client_ip(request)
    endpoint = request.url.path
    
    # Layer 1: Always check IP
    if not is_allowed_sliding_window(f"ip:{client_ip}", IP_LIMIT, IP_WINDOW):
        raise HTTPException(
            status_code=429,
            detail="Too many requests from this IP",
            headers={"Retry-After": "60"}
        )
    
    # Layer 2: Check user if authenticated
    if user_id:
        if not is_allowed_token_bucket(f"user:{user_id}", USER_LIMIT, USER_LIMIT/USER_WINDOW):
            raise HTTPException(
                status_code=429,
                detail="Rate limit exceeded. Please slow down.",
                headers={"Retry-After": "60"}
            )
    
    # Layer 3: Tighter limits for sensitive endpoints
    sensitive_endpoints = ["/auth/login", "/auth/register", "/auth/reset-password"]
    if endpoint in sensitive_endpoints:
        if not is_allowed_fixed_window(f"login:{client_ip}", LOGIN_LIMIT, LOGIN_WINDOW):
            raise HTTPException(
                status_code=429,
                detail="Too many authentication attempts",
                headers={"Retry-After": "60", "X-RateLimit-Limit": str(LOGIN_LIMIT)}
            )
 
 
@app.middleware("http")
async def apply_rate_limiting(request: Request, call_next):
    user_id = request.headers.get("X-User-ID")  # Set by auth middleware upstream
    await rate_limit_middleware(request, user_id)
    response = await call_next(request)
    return response

Distributed Rate Limiting — The Hard Part

A single Redis instance works fine until you have multiple API servers. The challenge: requests from the same client hit different servers, each with their own in-memory state.

Architecture

Client
  │
  ▼
Load Balancer
  ├── API Server 1 ──┐
  ├── API Server 2 ──┼──► Redis Cluster (shared state)
  └── API Server 3 ──┘

All servers share a single Redis cluster for rate limit state. This works well up to very high scale.

Redis Cluster Considerations

• Use Redis Cluster (not Sentinel) for horizontal scaling

• Hash slot distribution means related keys (same client) land on the same node — consistent

• Use connection pooling — don't open a new Redis connection per request

# Production Redis setup with connection pooling
import redis
 
pool = redis.ConnectionPool(
    host='your-redis-cluster-endpoint',
    port=6379,
    max_connections=50,
    socket_connect_timeout=1,
    socket_timeout=1
)
 
r = redis.Redis(connection_pool=pool)

What Happens When Redis Goes Down?

Two options and you need to decide upfront:

Fail open — if Redis is unavailable, allow all requests. Traffic flows, no revenue impact, risk of abuse.

Fail closed — if Redis is unavailable, reject all requests. No abuse, but service is degraded for legitimate users.

For most APIs, fail open with alerting is the right call. Add a circuit breaker:

import time
 
redis_healthy = True
last_redis_check = 0
 
def is_allowed_with_fallback(client_id: str, limit: int, window: int) -> bool:
    global redis_healthy, last_redis_check
    
    # Check Redis health every 5 seconds
    if not redis_healthy and time.time() - last_redis_check > 5:
        try:
            r.ping()
            redis_healthy = True
        except:
            last_redis_check = time.time()
            return True  # Fail open
    
    try:
        result = is_allowed_sliding_window(client_id, limit, window)
        redis_healthy = True
        return result
    except Exception:
        redis_healthy = False
        last_redis_check = time.time()
        return True  # Fail open — allow request, log the issue

Response Headers — Don't Forget These

Always return rate limit headers so clients can self-throttle:

from fastapi import Response
 
def add_rate_limit_headers(
    response: Response,
    limit: int,
    remaining: int,
    reset_at: int  # Unix timestamp
):
    response.headers["X-RateLimit-Limit"] = str(limit)
    response.headers["X-RateLimit-Remaining"] = str(max(0, remaining))
    response.headers["X-RateLimit-Reset"] = str(reset_at)
    response.headers["Retry-After"] = str(reset_at - int(time.time()))

Well-behaved API clients use these headers to back off automatically — which means fewer retries hammering your system when limits are hit.

Where to Put the Rate Limiter

You have three options:

Option 1: API Gateway (AWS API Gateway / Kong)

• Easiest to set up — configure, not code

• Limited flexibility — hard to do per-user logic

• Good for baseline IP protection

Option 2: Middleware in your application

• Full control over logic

• Access to user context, request data, business rules

• The implementation shown above

Option 3: Dedicated rate limit service

• Centralised policy management across multiple services

• More infrastructure to maintain

• Worth it at large scale (10+ services)

For most teams: start with middleware, move to a dedicated service when you have 5+ services that need a consistent rate-limiting policy.

Key Takeaways

1. Fixed Window is fine for low-stakes internal APIs — don't over-engineer

2. Sliding Window is the pragmatic choice for most public APIs — good accuracy, low cost

3. Token Bucket is best when some bursting is acceptable and expected

4. Leaky Bucket is for protecting downstream services that need perfectly smooth traffic

5. Layer your limits — IP-level and user-level serve different purposes, use both

6. Always use Lua scripts in Redis for rate limit operations — atomicity is not optional

7. Decide your Redis failure mode upfront — fail open or fail closed, document it

8. Return rate limit headers — good clients will use them and reduce your load

What Would You Do Differently?

Every system has different constraints. Some teams need per-organisation limits, per-endpoint limits, or dynamic limits that change based on subscription tier.

What's the most interesting rate-limiting challenge you've tackled? Drop it in the comments — I read every one.

If you found this useful, follow me on LinkedIn where I post about system design, AWS, and engineering career growth every week.

Search "URL shortener system design" and you'll find hundreds of articles. Most of them give you the same thing: a single server, a database with a short_code column, and a redirect endpoint.

That works for a demo. It doesn't work for production.

The real challenge isn't building a URL shortener. It's building one that handles millions of redirects per day, stays available when things go wrong, and doesn't cost a fortune to run. Those constraints change every decision you make.

Here's how I'd actually design it on AWS — and the tradeoffs I'd make along the way.

Requirements First

Before touching architecture, let's be explicit about what we're building.

Functional requirements:

• Given a long URL, generate a short code (e.g. sho.rt/xK92p)

• Given a short code, redirect to the original URL

• Short codes should be unique and ideally human-readable enough to share

• Optional: custom aliases, expiry dates, click analytics

Non-functional requirements:

• Reads (redirects) massively outnumber writes (URL creation) — think 100:1 ratio

• Redirect latency must be low — under 50ms ideally

• High availability — if this goes down, every link on the internet that uses it breaks

• Short codes must not collide

These constraints drive every architectural decision below.

The Naive Approach (And Why It Fails)

Most tutorials suggest this:

User → Web Server → Database (lookup short_code) → Redirect

Simple. Works at a low scale. Falls apart fast because:

• Every redirect hits the database — at 10,000 requests/second, your DB is the bottleneck

• Single server = single point of failure

• No geographic distribution — users in Sydney hitting a server in us-east-1 get 200ms+ latency

Let's fix all of this.

The Architecture I'd Actually Build

Here's the high-level design:

User
 │
 ▼
CloudFront (CDN + Edge Caching)
 │
 ▼
API Gateway
 │
 ├──► Lambda (URL Creation) ──► DynamoDB
 │
 └──► Lambda (URL Redirect) ──► ElastiCache (Redis)
                                      │
                                      └──► DynamoDB (cache miss)

Let me walk through each component and the reasoning behind it.

Component Breakdown

1. CloudFront — Your First Line of Defense

CloudFront sits in front of everything. For a URL shortener, this is critical because:

• Redirects for popular URLs get cached at the edge — a link that goes viral serves millions of requests without ever hitting your origin

• 400+ edge locations globally mean low latency for everyone

• Built-in DDoS protection via AWS Shield Standard

The cache key matters here. You want to cache on the short code, not the full URL. Set a short TTL (30-60 seconds) for most URLs, longer for ones you know won't change.

One important caveat: don't cache 301 redirects. Browsers cache 301s permanently, which means if you ever need to update a destination URL, users with cached responses are stuck. Use 302 (temporary redirect) instead — CloudFront caches it, browsers don't.

2. Short Code Generation — The Part Everyone Gets Wrong

This is where most designs fall apart. Common approaches:

Option A: Auto-increment ID + Base62 encoding

Take a database sequence (1, 2, 3...), encode it in Base62 (0-9, a-z, A-Z), and get short codes like b, c, 1a, 1b.

Problems:

• Sequential codes are predictable — someone can enumerate all your URLs

• Requires a centralised counter — creates a bottleneck

Option B: Random UUID + truncate

Generate a UUID, take the first 7 characters. Simple. But collision probability increases as your dataset grows, and you need collision checks on every write.

Option C: What I'd actually use — Snowflake-style ID + Base62

Generate a time-ordered unique ID (similar to Twitter's Snowflake) and encode it. You get:

• Roughly time-ordered codes (good for debugging)

• Extremely low collision probability without a central counter

• 7-character codes that support ~3.5 trillion unique URLs

On AWS, you can implement this in Lambda with a combination of timestamp + random bits + worker ID (derived from the Lambda execution environment).

3. DynamoDB — The Right Database for This Problem

Why DynamoDB over PostgreSQL or MySQL?

• Access pattern is simple: you're almost always looking up by short_code. DynamoDB is optimised for exactly this.

• Scales horizontally without configuration — you don't manage sharding

• Single-digit millisecond latency at any scale

• On-demand capacity means you only pay for what you use — perfect for spiky traffic

Table design:

Table: urls
Partition Key: short_code (String)

Attributes:
- original_url (String)
- created_at (Number — Unix timestamp)
- expires_at (Number — TTL attribute, DynamoDB auto-deletes)
- created_by (String — user ID if authenticated)
- click_count (Number — updated asynchronously)

Set expires_at As your TTL attribute and DynamoDB handles expiry automatically — no cron jobs needed.

4. ElastiCache (Redis) — Making Redirects Fast

Even DynamoDB at ~5ms is too slow if you want sub-50ms redirects globally. The solution: cache the short_code → original_url mapping in Redis.

Cache strategy: Cache-aside (lazy loading)

1. Request comes in for /xK92p
2. Check Redis — cache hit → redirect immediately (~1ms)
3. Cache miss → query DynamoDB → cache result → redirect (~10ms)

What to cache: Only redirects, not the creation flow. The creation flow is rare; redirects are constant.

TTL: Set Redis TTL to match your use case. For general URLs, 24 hours is reasonable. For URLs you know are temporary, match the expiry.

Cache invalidation: If a user deletes or updates a URL, invalidate the Redis key immediately. Don't wait for TTL expiry.

5. Lambda — Keeping Infrastructure Costs Low

Two Lambda functions handle the core logic:

URL Creation Lambda:

• Validates the input URL (is it actually a URL? Is it safe?)

• Generates the short code

• Writes to DynamoDB

• Returns the short URL

URL Redirect Lambda:

• Checks Redis cache

• Falls back to DynamoDB on cache miss

• Returns a 302 redirect

Why Lambda over EC2 or ECS? For this workload, Lambda is ideal:

• You pay per request, not per idle server

• Auto-scales to millions of requests without configuration

• No servers to manage or patch

The one concern with Lambda is cold starts. For the redirect function specifically, cold starts add latency. Mitigate this with Provisioned Concurrency on the redirect Lambda — keep a pool of warm instances ready.

The Analytics Problem

Most tutorials ignore click analytics entirely. But it's one of the most requested features.

The naive approach — incrementing a counter in DynamoDB on every redirect — is dangerous at scale. At 10,000 redirects/second on one URL, you'll hit DynamoDB write throughput limits and slow down redirects.

Better approach: Decouple analytics from the redirect path.

Redirect Lambda
 │
 └──► Kinesis Data Firehose (async, non-blocking)
              │
              ▼
           S3 (raw events)
              │
              ▼
        Athena (query analytics on demand)

The redirect happens immediately. The analytics event is fired asynchronously. The user never waits for analytics to complete.

For real-time dashboards, add a stream processor between Kinesis and a time-series store like DynamoDB or InfluxDB.

Handling Scale: The Numbers

Let's validate this architecture against real numbers.

Assumptions:

• 100 million redirects per day

• 1 million new URLs created per day

• Average URL size: 200 bytes

Storage: 1M URLs/day × 200 bytes × 365 days = ~73GB/year. DynamoDB handles this trivially.

Redirect throughput: 100M/day = 1,160 requests/second average, with peaks 10x higher (12,000 rps). With CloudFront caching popular URLs, most of this never hits your Lambda functions.

Cost estimate (rough):

• CloudFront: ~$10-15/month at this scale

• Lambda: ~$20-30/month

• DynamoDB (on-demand): ~$50-100/month depending on cache hit rate

• ElastiCache (small instance): ~$30/month

Total: ~$100-150/month for a system handling 100 million redirects per day. That's the power of serverless-first architecture.

What I'd Skip in V1

Not everything needs to be built on day one. Here's what I'd defer:

• Custom domains (e.g. company.com/abc) — complex to implement, add later

• Link previews / Open Graph — nice to have, not essential

• Real-time analytics dashboard — build the data pipeline first, the UI later

• Multi-region active-active — unless you have users on multiple continents from day one, start single-region and expand

The architecture above scales to hundreds of millions of requests before you need to rethink it. That buys you time to learn what your users actually need before over-engineering.

Key Takeaways

1. Reads dominate writes — design your caching strategy around the redirect path, not the creation path

2. Use 302, not 301 — browser caching of 301s will haunt you

3. Decouple analytics — never let analytics slow down the critical path

4. Short code generation is harder than it looks — think carefully about collision probability and enumeration attacks

5. CloudFront is doing more work than your servers — invest time in your cache invalidation strategy

What Would You Change?

This is one way to approach it — not the only way. I've made deliberate tradeoffs here that might not fit every use case.

What would you design differently? Would you choose a different database, a different caching strategy, or a different approach to short code generation?

Drop your thoughts in the comments — I read every one.

If you found this useful, follow me on LinkedIn where I post about system design, AWS, and engineering career growth every week.

For most engineers, shipping an application to production is more difficult than building it. The friction lies not in writing code but in setting up a reliable, secure, and maintainable infrastructure. Typical requirements include:

• Configuring VPC networking and security groups

• Provisioning an RDS PostgreSQL instance with encryption and backups

• Deploying containerized workloads on ECS Fargate with auto-scaling

• Managing load balancers, SSL termination, and health checks

• Setting up observability with monitoring and logging

• Running database migrations in a controlled manner

• Applying security best practices across all layers

• Keeping infrastructure costs predictable and under control

Without standardized practices, this process often extends into weeks of experimentation and patchwork fixes—time that could be better spent improving the application itself.

The Approach: Infrastructure as Code, Ready for Production

This solution encapsulates production-grade AWS infrastructure in a set of Terraform modules, designed to be deployed with a single command:

terraform apply -var-file=environments/stage/stage.tfvars

The result: a repeatable, secure, and auto-scaling deployment that can be provisioned in under 10 minutes.

Architecture Overview

Compute Layer

• ECS Fargate for container workloads (serverless execution, no cluster management)

• Auto-scaling policies triggered by CPU utilization

• Zero-downtime deployments via rolling updates

• Multi-AZ support for resilience

• Configurable health checks for seamless load balancer integration

Database Layer

• PostgreSQL 16.3 on Amazon RDS

• Encryption at rest with AWS KMS

• Automated daily backups with point-in-time recovery (7-day retention)

• Storage auto-scaling up to 100 GB

• IAM authentication for secure developer access

• Single-AZ (default) for cost efficiency, with Multi-AZ as an option

Networking & Security

• Custom VPC with public and private subnets across two Availability Zones

• Security groups applying least-privilege principles

• NAT Gateway for outbound internet traffic isolation

• Application Load Balancer with optional HTTPS support

• Private subnets isolating application and database resources

DevOps & Monitoring

• ECR as a private container registry with vulnerability scanning

• CloudWatch for centralized metrics, logs, and alarms

• CI/CD integrations with GitHub Actions and GitLab CI/CD pipelines

• Database migrations run as ECS tasks, optionally using Spot capacity for cost savings

• Terraform workspaces supporting multiple environments (dev, staging, prod)

Cost Analysis (us-east-1 reference)

This setup delivers production-grade reliability for ~$85–$120/month depending on workload and scaling.

Optimizations include single NAT Gateway usage, Spot ECS tasks for migrations, and right-sized defaults. Regional pricing variations apply (e.g., NAT Gateway costs in eu-west-1 are higher than in us-east-1).

Security Model

Security is applied consistently at multiple layers:

• Network-level isolation: workloads and databases run in private subnets with no direct internet access.

• Access control: IAM roles scoped to minimal privileges, IAM-based DB authentication, image scanning in ECR.

• Data protection: RDS encryption at rest, TLS in transit, automated backups with deletion protection.

Developer Experience

One-Command Deployment

terraform apply -var-file=environments/prod/prod.tfvars

CI/CD Integration

• Example pipelines included for GitHub Actions and GitLab CI/CD

• Infrastructure changes and application deployments handled in the same workflows

• Automated DB migrations via ECS task definitions

Multi-Environment Support

terraform workspace new dev
terraform workspace select prod
terraform apply -var-file=environments/prod/prod.tfvars

Configurability

All parameters—VPC CIDR, subnets, ECS task sizes, database classes, retention policies—are exposed via tfvars with sensible, secure defaults.

Modularity and Maintainability

Infrastructure is decomposed into reusable Terraform modules:

modules/
├── vpc/      # Networking
├── rds/      # Database
├── ecs/      # Compute
├── ecr/      # Container registry
├── alb/      # Load balancing
└── logging/  # Monitoring

This structure encourages reusability across projects, versioning through Git, and collaborative workflows with remote state.

Monitoring & Observability

• CloudWatch metrics and alarms for ECS and RDS thresholds

• Centralized logging for ECS tasks and ALB

• Health checks for applications and databases

• Configurable retention to balance visibility with cost

Practical Benefits

• For Individual Developers: Focus on building features instead of setting up networking and databases.

• For Teams: Consistent environments across dev/staging/prod, reducing onboarding time and configuration drift.

• For Startups: Production-quality infrastructure without dedicated DevOps resources, with predictable costs.

Getting Started

Prerequisites: AWS CLI, Terraform (≥1.6.0), Docker, and an S3 bucket for remote state.

git clone <repo-url>
cd infra
terraform init -backend-config=environments/stage/backend.conf
terraform workspace new stage
terraform apply -var-file=environments/stage/stage.tfvars

Outputs include ALB DNS name, ECR repository URL, and RDS endpoint for application integration.

Extending the Foundation

Common extensions include Redis/ElastiCache for caching, S3 for object storage, SES for email, and SQS/SNS for messaging. The design also supports scaling to multi-region deployments, CDN integration with CloudFront, and Kubernetes via EKS.

Repository

You can find the full source code here: Gitlab Repository

Conclusion

Provisioning production-ready AWS infrastructure is no longer a multi-week effort. With this Terraform-based approach, developers can:

• Deploy in minutes with one command

• Operate within a cost-efficient range (~$85–$120/month)

• Inherit AWS security best practices out of the box

• Scale seamlessly from development to production environments

This setup is not just infrastructure—it’s a framework for developer velocity and operational reliability.

It's 3 PM on a Wednesday. You're deep in the zone, crushing that new feature that's been on your backlog for weeks. Lines of code are flowing like poetry, your IDE is humming with activity, and you're making progress on multiple fronts simultaneously. You've refactored three components, fixed two bugs, updated the documentation, and added that shiny new feature your product manager has been asking for.

Then disaster strikes.

Your teammate Sarah messages you: "Hey, can you quickly revert that authentication bug fix from yesterday? It's causing issues in production."

You freeze. Yesterday's commit? That was part of your massive 47-file, 2,847-line commit that included the bug fix, but also the complete redesign of the user dashboard, database schema changes, and a refactor of the entire notification system.

Sound familiar? If you've been developing for more than a week, you've probably lived this nightmare.

The Monolithic Commit Monster

We've all been there. The commit message reads something like "Fixed stuff and added features" with a diff that spans across dozens of files. It's the developer equivalent of shoving everything into your bedroom closet before guests arrive – it might look clean from the outside, but good luck finding anything later.

Here's what a typical "monster commit" looks like:

commit a1b2c3d4e5f6789...
Author: John Developer <john@example.com>
Date: Tue Oct 15 18:45:22 2024 -0700

    Fixed bugs and improved UI

    Modified files:
    - src/components/UserDashboard.js (156 additions, 89 deletions)
    - src/components/Navigation.js (67 additions, 23 deletions)  
    - src/api/auth.js (45 additions, 12 deletions)
    - src/styles/main.css (234 additions, 156 deletions)
    - database/migrations/add_user_preferences.sql (23 additions, 0 deletions)
    - README.md (12 additions, 3 deletions)
    - package.json (3 additions, 1 deletion)
    ... and 23 more files

This commit is a debugging nightmare waiting to happen. What exactly did it fix? Which UI improvements were made? If something breaks, what do you revert? It's like trying to untangle Christmas lights in the dark.

Enter the Atomic Commit Philosophy

The atomic commit approach is beautifully simple: one logical change per commit. Each commit should represent a single, complete, and reversible change that makes sense on its own.

Instead of the monster above, imagine this sequence:

commit f1e2d3c4b5a6...
Author: John Developer <john@example.com>
Date: Tue Oct 15 14:30:22 2024 -0700

    Fix authentication timeout bug in login flow

    - Increase session timeout from 30 minutes to 2 hours
    - Add proper error handling for expired sessions
    - Update auth middleware to handle timeout gracefully

    Fixes: #1247

commit e1d2c3b4a5f6...
Author: John Developer <john@example.com>
Date: Tue Oct 15 15:15:33 2024 -0700

    Improve navigation menu accessibility

    - Add ARIA labels to all navigation items
    - Implement keyboard navigation support
    - Increase color contrast for better visibility

    Closes: #1156

commit d1c2b3a4f5e6...
Author: John Developer <john@example.com>
Date: Tue Oct 15 16:45:12 2024 -0700

    Add user preference persistence to database

    - Create user_preferences table migration
    - Add UserPreference model with validation
    - Implement CRUD operations for preferences

    Related: #1203

Now when Sarah asks you to revert that authentication fix, you can cherry-pick exactly what needs to be undone without affecting anything else.

Real-World Benefits in Action

Here's how atomic commits transform common development scenarios:

Code Reviews: Instead of reviewing one 400-line mixed change, you review five focused commits with clear purposes. Reviews become faster and feedback more targeted.

Debugging: When QA reports an avatar display bug, git log --grep="avatar" immediately shows the four avatar-related commits. You can pinpoint the issue in minutes instead of hours.

Hotfix Deployment: Production has a payment bug, but the release also contains new features already announced to customers. With atomic commits, you revert just the problematic "Optimize payment validation" commit while keeping everything else.

Feature Management: Your PM wants the new search filters in tomorrow's release, but not the redesigned results page. Clean commits let you cherry-pick exactly what's needed in minutes.

Key Technical Advantages

Git Bisect: Find bugs faster by testing logical changes instead of mixed commits. Each bisect step tells you exactly what functionality was added.

Cleaner Conflicts: Atomic commits create focused merge conflicts that are easier to resolve intelligently.

Flexible History: Easily reorder commits, split branches at logical boundaries, or create targeted backports with git rebase -i.

Practical Implementation Strategies

The Staging Area is Your Friend

Use git add -p to stage changes interactively. This lets you commit related changes while leaving other modifications for separate commits:

# You've modified authentication.js and user-profile.js
git add -p authentication.js  # Stage only auth-related changes
git commit -m "Fix session timeout handling"

git add user-profile.js
git commit -m "Add profile picture upload validation"

The WIP Commit Workflow

Don't let the fear of "imperfect" commits stop you. Use Work In Progress (WIP) commits freely:

git commit -m "WIP: Start implementing user search"
# Continue coding
git commit -m "WIP: Add search backend logic"
# More coding  
git commit -m "WIP: Connect frontend to search API"

Before pushing or opening a pull request, use git rebase -i to clean up your WIP commits into logical, atomic changes.

Commit Message Templates

Create a commit message template to maintain consistency:

# ~/.gitmessage
# [type]: [short description]
#
# [longer description if needed]
#
# Fixes: #[issue number]
# Closes: #[issue number]  
# Related: #[issue number]

# Types: feat, fix, docs, style, refactor, test, chore

Configure git to use it: git config commit.template ~/.gitmessage

Commit Message Templates

Create a commit message template to maintain consistency:

# ~/.gitmessage
# [type]: [short description]
#
# [longer description if needed]
#
# Fixes: #[issue number]
# Closes: #[issue number]  
# Related: #[issue number]

# Types: feat, fix, docs, style, refactor, test, chore

Configure git to use it: git config commit.template ~/.gitmessage

Common Objections (And Why They're Wrong)

"It Takes Too Much Time"

Reality: You're going to spend time organizing your changes anyway – either upfront (with atomic commits) or later (when debugging, reviewing, or reverting). Atomic commits front-load a small amount of effort to save massive amounts of time later.

"My Changes Are Too Interconnected"

Reality: If your changes truly can't be separated, that might indicate a design problem. Most "interconnected" changes can be broken down:

1. Add new functionality without using it

2. Refactor existing code to support the new functionality

3. Connect the new and existing functionality

4. Remove old/deprecated code

"Code Reviews Will Have Too Many Commits"

Reality: Reviewers prefer many small, focused commits over one large, mixed commit. It's easier to review five 50-line commits than one 250-line commit.

Building the Habit

Start Small

Begin by committing more frequently, even if the commits aren't perfect. You can always clean them up later with git rebase -i.

Use a Timer

Set a timer for 25-30 minutes. When it goes off, assess if you have something worth committing. This creates a natural rhythm and prevents hours-long coding sessions without commits.

Practice the Squash and Merge Workflow

Many teams use "squash and merge" for pull requests, which can make developers lazy about commit hygiene. Fight this by treating your feature branch commits as a story for your reviewers, then squash only at merge time.

Review Your Own Commits

Before pushing, run git log --oneline -10 and ask yourself:

• Can I understand what each commit does?

• Would I be comfortable reverting any individual commit?

• Do the commit messages tell a coherent story?

The Long-Term Impact

After six months of practicing atomic commits, here's what developers typically report:

• Debugging time reduced by 40-60%: Finding the source of bugs becomes systematic rather than exploratory

• Code review cycles shortened: Reviewers can provide more targeted, useful feedback

• Deployment confidence increased: Teams can deploy partial features or quickly revert problematic changes

• Team collaboration improved: Clear commit history serves as documentation of decision-making

• Technical debt reduced: Small, focused changes are less likely to introduce subtle bugs

Conclusion: Your Future Self Will Thank You

Every monolithic commit is a small act of cruelty toward your future self. You're essentially saying, "Figure it out later, buddy" to the developer who will need to debug, modify, or revert your changes.

Atomic commits are an act of kindness – to your teammates, to your future self, and to anyone who will maintain your code. They transform your git history from a chaotic timeline of mixed changes into a clear narrative of intentional decisions.

The next time you're about to commit 15 files with a message like "Various fixes and improvements," stop. Take five minutes to separate your changes into logical commits. Your 3 PM Wednesday self – the one dealing with production issues and impossible deadlines – will thank you.

Start tomorrow. Make your next commit atomic. Your development life will never be the same.

What's your biggest atomic commit success story? Share it in the comments below, and let's help more developers discover the joy of clean git history.

It feels good — being the person everyone turns to when things get tough. It feels like impact.

But here’s what I’ve learned over the years: being the hero often does more harm than good — both to the team and to your own growth.

This post is about why that “lone wolf” style doesn’t scale, and what shifting away from it actually looks like in practice.

Why the Lone Hero Model Breaks Down

There’s no doubt that individual brilliance has a place in software development. But when everything revolves around one person:

Knowledge Silos Form

Critical parts of the codebase become “owned” by one person. When they’re away, everything slows down — not because others aren’t capable, but because nobody else has the full picture.

Technical Debt Sneaks In

Working solo often means fewer reviews and less feedback. Temporary hacks stay in place. Clever shortcuts turn into long-term headaches.

Career Growth Gets Stuck

It’s counterintuitive, but the more indispensable you make yourself, the harder it is to move forward. Senior and lead roles are about enabling others, not just being the one who can “do it all.”

Signs You Might Be Stuck in Cowboy Mode

This isn’t always obvious — it hides behind urgency and the desire to move fast. Some red flags:

• Thinking “faster alone” is always better:

  “It’ll take too long to explain.”
  “I’ll just handle this now and loop them in later.”

• Unhelpful commits:

    commit abc123...
    fix stuff
  

• Sparse documentation:
  READMEs that are outdated or missing. Functions like doThing() with no explanation why.

• Skipping discussions:
  Too busy coding to join design reviews or planning sessions.

What Shifting Away from This Looks Like

Moving away from “hero mode” doesn’t mean you stop coding. It means you stop being the single point of success or failure.

Work in the Open

Instead of disappearing to fix something, share your process:

## Debug Notes: User Sessions Timing Out

**What we saw**: Users logged out after ~15 min  
**What we checked**:  
- Session timeout (OK: 2h)  
- Redis connections (fine)  
- Load balancer (sticky sessions were off)  

**Fix**: Switched to Redis-backed sessions  
**Next steps**: Add monitoring on session distribution

Even this small act helps others understand what happened and why.

Involve Others Early

Before jumping into a complex feature:

1. State the problem: “We need to support 10× more concurrent users.”

2. Discuss options: vertical scaling, horizontal scaling, caching.

3. Talk trade-offs: cost, timeline, complexity.

4. Agree on a path: and note down why.

This isn’t bureaucracy — it’s avoiding the costlier problem of building the wrong thing quickly.

Treat Code Reviews as Learning Time

Reviews aren’t just approvals. They’re a chance to share reasoning, context, and lessons.

For your PRs, explain:

## Purpose
Adds rate limiting for API endpoints.

## Why Redis?
- Works across servers  
- Survives deploys  
- Minimal latency (see attached benchmarks)

## Risks
- Redis memory usage
- Potential false positives under high load

For others’ PRs, ask genuine questions. Share links. Suggest patterns, but don’t block unnecessarily.

Document as You Go

You don’t need perfect wikis — start with:

• A solid README

• A quick architecture sketch

• Common troubleshooting steps

The key is to lower the barrier for the next person.

A Realistic Way to Start

Shifting this habit isn’t about an overnight transformation. Try this sequence over a few months:

• Week 1: List systems where only you know how things work.

• Weeks 2–4: Pick one and write a clear setup guide, diagram, or walkthrough.

• Weeks 5–8: For your next big task, bring the team in early.

• Weeks 9–12: Do thoughtful reviews — not just approvals, but knowledge sharing.

The Impact on Your Career

Ironically, the moment you stop trying to be “indispensable,” you often become more valuable.

Teams appreciate developers who:

• Make others faster

• Leave trails others can follow

• Build systems that live beyond them

That’s the kind of work that leads to senior roles, tech lead positions, and the ability to influence across multiple projects — not just the one you’re currently “saving.”

Final Thought

Being a great developer isn’t just about the code you write. It’s about the systems you leave behind and the people you help grow.

Start small: write that README, share that debugging process, ask one more question in your next review. It adds up — for your team and for your career.

Have you ever had to break the “hero habit”? What was the turning point for you?

Amazon S3, or Simple Storage Service, is a cloud-based object storage service that allows users to store and retrieve any amount of data from anywhere on the internet. With its high scalability, durability, and security, S3 has become the go-to solution for image hosting, serving as a reliable and cost-effective alternative to traditional hosting services.

Here are some of the benefits of using AWS S3 as an image hosting service:

1. Cost-effective: S3 pricing is based on usage, making it a cost-effective solution for image hosting. With S3's pay-as-you-go pricing model, you only pay for the storage and bandwidth you use, with no upfront fees or long-term commitments. This makes S3 an ideal option for websites with varying traffic patterns or those looking to reduce their hosting costs.

2. High Scalability: S3 allows you to store an unlimited number of images and scales effortlessly to handle any increase in traffic. As your website grows and attracts more visitors, S3 can handle the increased traffic without any downtime or interruptions, making it a scalable solution for image hosting.

3. Durability: S3 is designed to ensure 99.999999999% durability and 99.99% availability of objects over a given year. This means that your images will always be available to your users, regardless of any hardware failures or network issues.

4. Security: S3 offers multiple security features to protect your images from unauthorized access, including access control lists, bucket policies, and encryption options. Additionally, S3 integrates with AWS Identity and Access Management (IAM) to provide granular access controls and identity management.

5. Easy Integration: S3 integrates seamlessly with other AWS services, such as CloudFront, Lambda, and API Gateway, to offer a complete solution for image hosting. This integration allows you to build a scalable and secure image hosting service that can handle any traffic load.

Let's dive into some code

Here's a Python code example for setting public access permissions on an S3 bucket using the Boto3 library:

import boto3

s3 = boto3.client('s3')

bucket_name = 'your-bucket-name'

response = s3.put_public_access_block(
    Bucket=bucket_name,
    PublicAccessBlockConfiguration={
        'BlockPublicAcls': False,
        'IgnorePublicAcls': False,
        'BlockPublicPolicy': False,
        'RestrictPublicBuckets': False
    }
)

As a developer working for a website that hosts images, this is just one of the steps in setting up the whole flow. Being a developer, I have also faced the issue of manually doing the whole flow.

Here comes automation (IaC). Infrastructure as code (IaC) refers to the process of managing and provisioning infrastructure through code and automation tools. AWS CloudFormation is an IaC service that enables users to create and manage AWS resources using templates and automation.

Here is a CloudFormation template that setups the whole flow for us. The template does the following things

1. An S3 bucket with public access

2. Attach the new S3 bucket with a Cloudfront CDN for faster access and caching

3. Create an IAM user with full access to the newly created S3 bucket

This template solves the burden of setting up this whole flow manually. You just need to run the following from your terminal or upload the template in your AWS console

aws cloudformation deploy --stack-name [STACK_NAME] --parameter-overrides Stage="[ENVIRONMENT]" BucketName="[BUCKET_NAME]" --template-file [PATH_TO_TEMPLATE] --region [REGION] --profile [PROFILE_NAME] --capabilities CAPABILITY_NAMED_IAM

In conclusion, AWS S3 is a reliable and cost-effective image hosting solution that offers a range of benefits, including high scalability, durability, security, and easy integration with other AWS services. If you're looking for an image hosting service that can handle your website's traffic and provide a seamless user experience, then AWS S3 is the perfect solution.

NOTE: I am a developer too. The template can have its fault. Feel free to comment or contact me directly through website/LinkedIn

Hope this was helpful. Thanks

Website: Madhav Bhasin

Github: Madhav Bhasin

Linkedin: Madhav Bhasin

• Working with Single SSH Keypair

It's quite easy working with a single SSH key pair

1. Create a new key pair

    ssh-keygen -t ed25519 -C "your_email@example.com"
    or
    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
   
    NOTE: Replace "your_email@example.com" with your own email
   

   Thinking what's ED25519 and RSA are? Do have a look at this SSH Key ED25519 vs RSA

   Use ED25519, it's more secure and faster

   After hitting one of the above commands you will be prompt to give a file name or use the default one. Personal preference you should give a new file name and not use the default one. NOTE: If you are going to have a new file name then you need to pass the full path, not just the file name e.g /Users/<USERNAME>/.ssh/my-new-ssh- key

   Hit Enter, give a new passphrase/password to your key, and TADA: It's done

2. Copy your public key and paste it on the server/repo

    on macOS
    pbcopy < ~/.ssh/[SSH_KEY_NAME].pub
   
    on linux 
    cat ~/.ssh/[SSH_KEY_NAME].pub
   

3. Test your SSH connection e.g I have generated my ssh key pair for my Github account then

     ssh github.com
   

   If everything is good then you will be seeing something like this

    Hi <USERNAME>! You've successfully authenticated, but GitHub does not provide 
    shell access.
   

• Working with Multiple SSH Keypair

  Managing SSH keys can become cumbersome as soon as you need to use a second key pair. You might be using one SSH key pair for working on your company’s internal projects but you might be using a different key for accessing some corporate client’s servers. We can have more such cases where we need to have multiple SSH key pairs.

1. Create another SSH key pair, follow the same steps as above

   When you test your connection you will see something like this

    connect to <server> host : Connection Refused
   

   Now, what's happened here. I am taking Github as an example here. You have 2 Github accounts and you have 2 different SSH public keys attached to them (Github doesn't allow to have the same SSH keys for 2 different accounts).

   Your Github account has an SSH public key and it's expecting the respective private key on your local machine. But it's not taking that, it's taking the default one because you have the same hostname github.com as the previous one. Here comes the SSH Config

2. SSH Config

   SSH allows you to set up a per-user configuration file where you can store different SSH options for each remote machine you connect to. By default, the SSH configuration file may not exist, so you may need to create it

     touch ~/.ssh/config
   

   This file must be readable and writable only by the user and not accessible by others

     chmod 600 ~/.ssh/config
   

   SSH Config File Example

    Host github.com-targaryen
         HostName github.com
         User git
         IdentityFile ~/.ssh/targaryen
   

   Here is what's going on :

   1. We have defined a Host/server for which we want to specify some rules

   2. Under that host we have defined some rules like the hostname, server user, and a IdentityFile (private key file)

      When a user (git) tries to connect to a host (github.com-targaryen), the SSH Agent will use the specified IdentityFile and not the default one.

      Solution for our current user case

      Host github.com-githubAccount1
           HostName github.com
           User git
           IdentityFile ~/.ssh/<FILE_NAME_1>
      
      Host github.com-githubAccount2  
           HostName github.com
           User git
           IdentityFile ~/.ssh/<FILE_NAME_2>
      

      NOTE: Here the FILE_NAME should be the respective private key file name. Also, you can change the hostname github.com-githubAccount1 to anything but you have to keep github.com-

IMPORTANT

When cloning/adding the remote to your git repository make sure you do this step :

Change the ssh clone URL a bit :

    Original
    git@github.com:<user>/<repo>.git

    Changed
    git@github.com-githubAccount1:<user>/<repo>.git

Noticed what changed? I have added a unique identifier after github.com. It's the same identifier that you added in the hostname while editing the SSH config file. It should be the same.

Hope this was helpful. Thanks

Website : Madhav Bhasin

Github : Madhav Bhasin

Linkedin : Madhav Bhasin

NOTE: I would appreciate any comments if I have missed anything.