DEV Community: M TOQEER ZIA

NATS and NATS Streaming: From Basics to Concurrency

M TOQEER ZIA — Mon, 27 Jul 2026 18:04:23 +0000

What is NATS?

NATS is a lightweight messaging system. Services send messages to named subjects, and other services listen on those subjects. The sender never needs to know who listens. The listener never needs to know who sends. This pattern is called publish and subscribe.

Core NATS works in a fire-and-forget way. A publisher sends a message to a subject. NATS delivers the message to every listener connected at that moment. No listener means no delivery. The message is gone.

Why use NATS?

In a monolith, one module calls another module through a direct function call. In microservices, each service runs as a separate process, often on a separate machine. Direct calls no longer fit. Services need a shared way to talk without tight links to each other.

NATS gives you three benefits:

Decoupling. The publisher sends an event and moves on. The publisher never tracks who reacts.
Scalability. A new service subscribes to existing events and reacts on its own. You change no publisher code.
Speed. NATS routes small messages fast, which suits high-traffic systems.

What is NATS Streaming?

Core NATS loses a message when no one listens. NATS Streaming, also called STAN, fixes this gap. NATS Streaming runs as a layer on top of core NATS and adds storage and delivery guarantees.

NATS Streaming adds four features:

Persistence. Messages get stored in memory, in a file, or in a SQL store.
Replay. A new subscriber requests messages from the start, from a sequence number, or from a point in time.
At-least-once delivery. Subscribers acknowledge each message, so a crashed service does not lose data.
Durable subscriptions. A service disconnects, reconnects, and resumes from the last processed message.

Here is the difference side by side:

Feature	Core NATS	NATS Streaming
Delivery	At most once	At least once
Persistence	None	Memory, file, or SQL
Replay	No	Yes
Durable subscriptions	No	Yes
Status	Maintained	Deprecated, end of life June 2023

One warning before you build on this. Synadia ended support for NATS Streaming in June 2023 and points teams to JetStream, the persistence layer built into the NATS server. Learn the concepts here and apply them in JetStream for production work.

The main purpose of NATS

The main purpose is to act as an event bus between microservices. A service publishes an event such as OrderCreated or TicketUpdated. Other services subscribe and react. The publisher stays decoupled from every consumer.

NATS Streaming works well as an event bus for four reasons:

No lost events on crash. Plain pub and sub drops events when a subscriber goes down. NATS Streaming stores them for later delivery.
Ordering support. Events on a subject arrive in order, which matters for state changes like created, reserved, paid, expired.
Replay for new services. A new service replays the full history from the start.
Retry through acknowledgements. Unacknowledged messages get redelivered, giving you built-in retry logic.

Publisher example

import nats from 'node-nats-streaming';

const stan = nats.connect('ticketing', 'abc', {
  url: 'http://localhost:4222',
});
// connect(clusterId, clientId, config)
//  - clusterId ('ticketing'): matches the server cluster ID
//  - clientId ('abc'): unique per client; a duplicate kicks off the first
//  - config.url: address of the NATS Streaming server

stan.on('connect', () => {
  console.log('Publisher connected');

  const data = JSON.stringify({ id: '123', title: 'concert', price: 20 });
  // NATS Streaming accepts strings or binary, so objects need JSON.stringify

  stan.publish('ticket:created', data, () => {
    console.log('Event published');
  });
});

The client ID sits hardcoded as 'abc' in this example. In a real deployment with many pod replicas of one service, every pod tries the same client ID and kicks the others off. Generate the ID at runtime from a random value or the pod name.

The duplicate processing problem

You scale a service by running more copies. Picture three replicas of orders-service in Kubernetes. Each replica opens its own subscription to the ticket:created channel. With no grouping, every replica receives every event. Three replicas save the same comment three times. You get duplicate work and corrupted data.

Queue groups fix duplicates

A queue group is a named group inside a channel. When several instances join one group, NATS delivers each event to a single member of the group. Your three orders-service replicas then process each event once.

Different services keep their own queue groups on the same channel. A payments service and an orders service each receive a copy of every event. Inside each group, one member does the work.

Think of a pizza shop with three chefs on one team. One chef makes each pizza. No duplicates. A waiter works on a separate team and hears every order alone.

In node-nats-streaming, you pass the queue group name as the second argument to subscribe(). Every replica of the same service uses the exact same name.

const queueGroupName = 'orders-service-queue-group';

Ordering is the harder problem

Queue groups stop duplicate work. Ordering across different events is a separate challenge. A banking app shows why. The rule is simple. The balance never drops below zero. Four failures break this rule.

An event fails to process. When a listener never acknowledges an event, NATS waits about 30 seconds and resends the event to another instance. Later events run before the failed one, and the balance goes negative.
One instance runs slower than another. Instance A holds a backlog. Instance B sits idle and fast. A withdrawal reaches Instance B and runs before an earlier deposit still waiting in Instance A. Wrong order again.
A service crashes. NATS needs time to detect a dead instance through heartbeats. Events sent to the dead instance wait until NATS times out and reassigns them. During the wait, other events run ahead.
A race near the timeout. A service takes close to 30 seconds. NATS marks the event as failed and resends the event to another instance. The original instance finishes right after. Two instances process the same event.

These failures are not NATS bugs. Any system with parallel work faces them.

The same problem lives everywhere

A common reaction is to drop events and use synchronous requests, or to return to a monolith. Neither move helps. Synchronous calls carry the same concurrency risks. A monolith behind a load balancer runs many instances and hits the same out-of-order failures. Microservices and events make the problem more visible through network hops, retries, and delivery delays. The root problem exists anywhere processes run in parallel.

Three solutions and why each falls short

Global shared sequence tracking. All instances share one store of the last processed sequence number. Before processing event N, a service checks for N minus 1. You get exact order and zero duplicates. The cost is severe. The whole system now processes one event at a time. Jim's stuck deposit blocks Mary's unrelated deposit. Throughput drops to the floor.

Per-user sequence numbers. Give each user an independent sequence, so Jim and Mary never block each other. Concurrency improves. NATS Streaming breaks the plan. Sequence numbers reset only inside a channel, so each user needs a separate channel. NATS Streaming handles a limited number of channels, with a default near 1,000 and real overhead per channel. Millions of users need millions of channels. No scale.

Publisher tracks the previous sequence. The publisher remembers each user's last sequence number and attaches the expected previous number to every new event. Consumers process an event only when the stored number matches the expected previous number. Clever, and broken. NATS Streaming never returns the assigned sequence number to the publisher. Publishing runs one way. The publisher never learns the number to track.

The real fix: your own version numbers

The lesson lands hard. The problem is your design, not NATS. Stop asking how NATS orders events. Ask how your services make ordering simple.

Look at a blog app. The Post Service owns Posts. No other service creates or edits a Post. This is a single source of truth. Apply the same rule to money. A Transaction Service owns transactions. The service receives requests, saves each transaction, and publishes events.

Then the service assigns its own numbers, one sequence per user.

Deposit 70 becomes transaction 1
Deposit 40 becomes transaction 2
Withdraw 100 becomes transaction 3

These numbers belong to your business, not to NATS. Every event carries userId, amount, and transactionNumber.

The Account Service listens and stores a balance plus the last transaction number. The rule is one line. Process an event only when the incoming number equals the stored number plus one.

Walk the failure. Event 1 crashes. Event 2 arrives with number 2. The stored last transaction is None. Expected previous is 1. No match. The Account Service skips the event and sends no acknowledgement. NATS resends Event 1 after 30 seconds. The service processes Event 1, sets the balance to 70, and stores 1. Event 2 arrives again. Expected 1 matches stored 1. Process. Balance 110. Event 3 arrives. Expected 2 matches stored 2. Process. Balance 10. Correct order, enforced by your logic, not by NATS.

Versioning in the ticketing app

The ticketing project applies the same idea with a version number. Only the Ticket Service changes a version.

TicketCreated ships version 1
TicketUpdated ships version 2
TicketUpdated ships version 3

The Order Service also needs ticket prices, so the Order Service listens. The rule stays the same. Accept an event only when the incoming version equals the stored version plus one. Version 3 arriving before Version 2 fails the check. The Order Service sends no acknowledgement and waits. NATS retries later. Version 2 lands, then Version 3 lands, and the final price reaches 100, the correct value.

The consumer stays behind or level with the producer, never ahead. Mongoose helps here with a built-in version field. You configure each update to increment the version and each event to carry the number.

Recovery and replay: three options together

A crashed service misses events while offline. NATS Streaming stores every published event, so recovery works. Three subscription options solve recovery together.

setDeliverAllAvailable() replays every stored event on startup. A brand-new service uses this once to build local state. The downside shows fast. Every restart replays the full history. Five events feel fine. Five million events waste hours of CPU and network on each restart.

setDurableName('order-service') gives the subscription a stable identity. NATS remembers the last event this subscription processed. On restart, NATS sends only the missed events, not the whole history.

Queue Group keeps one member processing each event and holds the durable state alive across brief disconnects. Without a queue group, a Ctrl+C looks like a permanent disconnect, so NATS drops the durable state and replays everything again.

Used together the behavior stays clean. First startup replays all history and records progress. A restart with no new events delivers nothing. A restart after missing Events 4 and 5 delivers only 4 and 5. Three Order Service pods share one durable subscription and split the load, one event per pod.

The takeaway

Every quick fix trades one problem for another. Global sequencing gives correct order and terrible speed. Per-user sequencing gives speed and hits channel limits. Publisher-tracked sequencing reads well and dies on a NATS limitation. The working answer moves ordering into your own design through business-level version numbers, then pairs setDeliverAllAvailable, setDurableName, and a queue group for reliable replay, fault tolerance, and horizontal scale.

Understanding the Event Bus: Publishers, Subscribers, and How Events Get Heard

M TOQEER ZIA — Thu, 23 Jul 2026 11:24:28 +0000

Sometimes a picture saves you 500 words of explanation. This post is the visual companion to the event bus / pub-sub concept — four diagrams, each unpacked so you can actually see how publishers and subscribers behave before you touch a single line of code.

If you already read the full write-up on event buses, think of this as the cheat-sheet version. If you haven't, this still stands on its own.

1. Direct calls vs. event bus

On the left is the classic mistake: OrderService reaches out and calls Email, Inventory, Payment, and Shipping directly. It has to know all four addresses, handle all four failure modes, and if one of them is slow, the whole checkout slows down with it.

On the right, OrderService does one thing: it publishes order.created to the event bus and moves on. It never finds out who picked it up, how many services are listening, or whether a new one gets added next sprint.

💡 Takeaway: the arrow count doesn't change — what changes is who owns the connection. With direct calls, the publisher owns every relationship. With a bus, the bus owns them, and the publisher owns none.

2. What's actually happening inside the bus

This is the part people skip past too quickly. The "bus" isn't one big pipe — it's a broker holding named topics (order.created, order.cancelled, payment.failed), and each topic can have multiple independent subscribers.

Notice Email Service, Analytics Svc, and Inventory Svc are all subscribed to the same topic here. Each one gets its own copy of the event. If Analytics Svc is slow to process it, Email Service doesn't wait around — they're not in a line, they're in parallel lanes.

💡 Takeaway: subscribing is a one-time registration. After that, delivery is automatic — the broker does the fan-out, not the publisher.

3. A real checkout, end to end

This is where the theory turns into an actual business flow. Read it top to bottom:

Checkout Service publishes order.placed — its job ends here.
Payment Service picks it up, charges the card, and publishes payment.confirmed.
Inventory Service reacts to that, reserves stock, and publishes stock.reserved.
Notification Service reacts to that and emails the customer.

Every step is a reaction to an event, never a direct request. If Notification Service is temporarily down, steps 1–6 still complete without a hiccup — the email just goes out a little later once it's back.

⚠️ Common mistake: assuming this chain always completes in order and instantly. It's asynchronous — build your system (and your customer-facing UI) to tolerate a short delay between "payment confirmed" and "email sent."

4. The cover — zoomed out

Zoom back out and this is the whole pattern in one picture: multiple publishers (Orders, Payments, Inventory) on the left, a single event bus in the middle, and multiple subscribers (Email, Analytics, Shipping, Fraud Check) on the right. Nobody on the left knows or cares who's on the right — that's the entire point of the architecture.

Quick recap

Diagram	What it shows
1	Why direct service-to-service calls create fragile, tightly coupled systems
2	How topics and multiple subscribers work inside the broker
3	A real, asynchronous e-commerce checkout flow, step by step
4	The full pattern zoomed out — many publishers, one bus, many subscribers

Next time you're sketching a system design on a whiteboard, try drawing it this way first. If you find yourself drawing arrows from one service to five others, that's usually the signal to introduce a bus.

Got a diagram of your own event-driven system? Drop it in the comments — always curious to see how different teams structure their topics.

Sharding, Explained: How to Talk About It in a System Design Interview

M TOQEER ZIA — Tue, 21 Jul 2026 06:14:20 +0000

Sharding is one of those topics that shows up in almost every system design interview once scale enters the conversation. Yet many candidates reach for it reflexively, without justifying whether it's actually needed, and without a clear framework for explaining how they'd do it. This article breaks down why sharding exists, how to choose a shard key, the main distribution strategies, the challenges sharding introduces, and how to bring all of this together in an interview setting.

Why Sharding Exists

Imagine you've just launched an app backed by a single large database — say an AWS RDS Postgres instance with around 70 terabytes of storage and the capacity to handle roughly 10,000 writes per second. In the early days, this is more than enough. Traffic grows, but the single database keeps up comfortably.

Eventually, though, growth catches up with you. Maybe you now need 20,000 writes per second, or your storage is creeping toward that 70 TB ceiling. Queries slow down, backups take forever, and it's clear you've hit a limit.

The first instinct is usually vertical scaling — move to bigger hardware. This buys you time. AWS offers machines that can handle upwards of 140 terabytes of storage and around 50,000 writes per second, and most companies will never even approach that ceiling. But if your app keeps growing — more users, global traffic, sustained load — even the biggest single machine eventually saturates its CPU, storage, and I/O.

At that point, no amount of vertical scaling solves the problem. This is when you reach for sharding.

What Sharding Actually Is

Sharding means splitting your data across multiple independent databases so that no single machine holds the entire dataset. Each shard is a standalone database with its own CPU, memory, storage, and connection pool, holding just a portion of the overall data. Need more capacity? Add another shard.

This solves the scaling problem, but it introduces a new set of questions: How do you decide how to split the data? How do you know which shard to query? What happens when one shard gets far more traffic than the others? What happens if a shard goes down and data needs to be rebalanced? Sharding trades a scaling problem for an operational complexity problem.

Choosing a Shard Key

The first decision in any sharding strategy is the shard key — the field used to determine how data is grouped and distributed. In an interview, this should be one of the first things you state explicitly, along with your reasoning.

A strong shard key has three properties:

High cardinality — many unique values, so data spreads across shards rather than clustering.
Even distribution — values that naturally spread out, so no shard ends up disproportionately large.
Query alignment — the key should match how the data is actually queried.

For example, if the dominant access pattern is "fetch all posts for a given user," sharding by user ID means each user's data lives on one shard, so most queries only need to hit a single database.

Good shard key examples:

A social media app where the core operation is loading a user's profile and posts → shard by user ID.
An e-commerce platform where the core operation is retrieving or updating a single order → shard by order ID.

Poor shard key examples:

A boolean field like "is premium user" — only two possible values, which caps you at two shards.
Creation date, in an app where most queries target recent data — this concentrates nearly all traffic on the newest shard, creating a hotspot.

How to Distribute Data Across Shards

Once you have a shard key, you need a strategy for mapping its values to specific shards.

Range-based sharding splits the key into contiguous ranges (e.g., user IDs 0–10M go to shard one, 10M–20M to shard two, and so on). It's simple and intuitive, but tends to produce uneven load — early shards may sit empty while the current range absorbs all new traffic, especially if IDs increase monotonically. It's a reasonable starting point but rarely used in production at scale.

Hash-based sharding is the industry default. You hash the shard key and mod the result by the number of shards to decide placement, which produces solid, even distribution. The catch is rebalancing: adding or removing a shard changes the modulus, which forces nearly all existing data to move. Consistent hashing solves this by placing both keys and shards on a virtual ring — you hash to a point on the ring and walk it to find the right shard, with refinements like virtual nodes to smooth out distribution further. This avoids the mass-reshuffling problem entirely. In interviews, especially at senior levels, hash-based sharding with consistent hashing is generally the expected default; at junior or mid-levels, you may need to explain the mechanics rather than simply naming it.

Directory-based sharding uses a lookup table that maps each record to a specific shard, rather than a formula. This gives you flexibility — you can move an overloaded user to their own dedicated shard just by updating the mapping. The tradeoff is an extra lookup on every request (added latency, two round-trips instead of one) and the directory itself becomes a single point of failure. It's rarely the default answer in interviews but is useful to mention as an option when flexibility matters more than raw throughput.

The practical takeaway: default to hash-based sharding with consistent hashing, and bring up the alternatives only when the scenario calls for them.

The Core Challenges Sharding Introduces

Hotspots and Load Imbalance

Even a well-chosen shard key can produce uneven load in practice — the classic "celebrity problem." If you shard by user ID and one extremely popular user's data lands on a single shard, that shard can get flooded with traffic while others sit idle. Two common fixes:

Compound shard keys, which append extra data (like a number or time bucket) to the key before hashing, spreading one entity's data across multiple shards.
Dedicated shards for outliers, where high-traffic entities are detected and routed via a directory lookup to a special, higher-capacity shard, while everyone else follows the standard hashing scheme.

Most systems never need this, but platforms with extreme traffic outliers — large social networks, for instance — often do.

Cross-Shard Operations

Some queries need data from more than one shard, requiring a fan-out to multiple databases and then aggregation of the results — far more expensive than a single-shard query. This usually happens when a query doesn't align with the shard key. Fetching one user's profile is cheap; fetching "the ten most popular posts across the entire platform" requires querying every shard and combining the results.

You can't eliminate cross-shard queries completely, but you can minimize their cost:

Cache expensive cross-shard results (in something like Redis) with an expiration, trading some staleness for speed — useful for feeds, leaderboards, and trending pages.
Denormalize data so related information lives on the same shard, reducing the need for cross-shard reads at the cost of more complex writes.

If cross-shard queries keep showing up for common use cases, that's usually a sign the shard key needs rethinking, or that caching and denormalization should be applied more aggressively.

Consistency Across Shards

On a single database, a transaction like transferring money between two accounts is atomic by default — both updates succeed, or neither does. Once those two accounts live on different shards, that guarantee breaks down, and a partial failure can leave the system in an inconsistent state.

The textbook fix is two-phase commit (2PC), where a coordinator asks every involved shard if it's ready, waits for agreement, and then tells them all to commit. In practice, 2PC is slow and fragile — if a shard or the coordinator fails mid-process, the system can get stuck in a hard-to-resolve locked state, which is why most production systems avoid it.

Better alternatives:

Avoid cross-shard transactions where possible, by keeping transactionally related data on the same shard.
Use the saga pattern, breaking a transaction into a sequence of smaller steps, each with a compensating action to undo it if a later step fails — rather than relying on an atomic rollback.

Bringing It Together in an Interview

Sharding usually comes up during the deep-dive portion of a system design interview, when you're addressing a non-functional requirement around scale. Before proposing it, do the math on storage, write throughput, and read throughput to justify whether sharding is actually necessary.

For example: 500 million users at 5 KB each is only about 2.5 TB — well within the range a single Postgres instance can handle comfortably. But 50,000 writes per second at peak would strain a single database, which is a legitimate reason to shard. High read volume from a large active user base, even with read replicas in place, can also justify distributing load.

This distinction matters. Modern single-instance hardware can go a long way — well past 100 TB of storage and tens of thousands of writes per second. Many candidates jump straight to sharding without checking whether it's warranted; showing the math for why sharding isn't necessary yet can be just as impressive as knowing how to implement it.

When sharding is justified, structure your answer around four steps:

Propose a shard key based on the dominant access pattern (e.g., shard by user ID because most queries are user-centric).
Choose a distribution strategy — typically hash-based sharding with consistent hashing, explained in more depth if you're earlier in your career.
Call out the tradeoffs, such as cross-shard queries becoming more expensive, and how you'd mitigate that with caching or precomputation.
Address future growth, such as starting with enough shards for headroom and noting that consistent hashing makes adding more shards later far less disruptive.

Delivered well, this shouldn't feel like a checklist — it should read as a natural progression from the numbers you've calculated to the design decisions those numbers demand.

Testing Microservices: Scope, Strategy, and the Auth Service Test Setup

M TOQEER ZIA — Thu, 16 Jul 2026 07:24:53 +0000

A practical breakdown of how to think about and implement automated testing in a microservices architecture — using an Auth service (Express + TypeScript + MongoDB) as the working example.

1. Why This Matters (The Problem)

Up to this point, the auth service (and the broader app) had no automated tests — only manual testing done through Postman. That's fine for quick checks, but it doesn't scale, doesn't run in CI, and doesn't protect you when you refactor.

So the goal here is to build a real automated testing setup — but before writing a single line of test code, you need to answer a more fundamental question:

"What exactly am I testing, and how much of the system am I trying to cover in one test?"

This is the scope problem, and it's the single biggest decision in microservices testing.

2. The Four Levels of Test Scope

In any microservices system, tests can span a spectrum from very narrow to very broad. This list isn't exhaustive, but it captures the main levels you'll encounter:

#	Scope	What it tests	Example
1	Unit test	A single piece of code in isolation	Testing one middleware function on its own
2	Integration within a service	Multiple pieces of code working together	A request flowing through `requireAuth` middleware → into a route handler
3	Component interaction	How a service talks to an external system ("component" here means a program, not a UI component)	Testing how the service interacts with MongoDB, or with an event bus
4	Cross-service test	How two or more independent services work together	Launching the Orders service and the Ticketing service together, having one emit an event, and checking the other processes it correctly

Why not just always test at the biggest scope (#4)?

It's tempting to think: "Let's just test how all the services work together — that's closest to real life!"

But in practice, this is extremely complex and expensive to set up. Think about what it would actually require:

Spinning up a temporary Kubernetes cluster
Deploying multiple services into it just for the test
Figuring out how to send requests into that environment
Figuring out how to assert on results coming out of it

That's a lot of infrastructure just to run a test suite. It's slow, costly, and fragile.

The Decision

Because of that complexity, the strategy here is:

Test each service in isolation. Don't try to launch multiple services together to test their interaction directly.

Instead, cross-service behavior will be tested indirectly — through event emitting and receiving (more on this below). This gets you most of the confidence of a full integration test without the operational overhead.

3. The Three Kinds of Tests You'll Actually Write (Per Service)

For each individual service (starting with Auth), there are three categories of tests to focus on:

Test Goal #1 — Basic Request Handling

Send a request into the service and assert on the outcome. For example:

Hit the sign-up endpoint → expect a response with a cookie containing a JWT
Assert that the expected data was written into MongoDB

This is the first and primary focus for the Auth service right now.

Test Goal #2 — Model-Level Unit Tests

Test the behavior of a specific data model in isolation (e.g., a method on the User model).

Not very relevant for Auth right now, since the User model is simple. But later services will have more complex models that need this kind of testing.

Test Goal #3 — Event Emitting & Receiving

Test that a service:

Correctly receives an incoming event and processes it properly
Correctly emits an event to the outside world

Not applicable yet — the app doesn't send or receive events at this stage, and event infrastructure hasn't been built.

Why Test Goal #3 matters long-term

This is the key insight: testing events is how cross-service behavior gets tested, without needing to launch multiple services together.

Instead of running Orders + Ticketing simultaneously (scope level #4 — expensive and complex), you can:

Test that the Orders service emits the correct event
Test that the Ticketing service receives and processes that event correctly

Each of these can be tested within a single service in isolation, but together they give you confidence that the services will work correctly when connected in the real world.

4. How Tests Will Actually Be Run

The practical execution model is intentionally simple:

Tests run directly in the terminal on your local machine
No Docker, no Kubernetes involved in running the tests themselves
Command: npm run test
This spins up the service locally and runs tests against it

The underlying assumption

This approach assumes your local machine can fully run the service — meaning all its dependencies (Node.js, MongoDB, etc.) are available locally without a complex setup.

For the Auth service right now, that's true — you only need Node.js and MongoDB.

A note on future complexity

Not every future service will be this simple. Some may need a specific OS, or a complex, hard-to-install database. When that happens, this simple "just run it locally" approach won't hold up — a more advanced testing setup will be needed later. For now, though, local execution is the right call.

5. Setting Up the Test Pipeline

The plan for how a single test run works, using Jest as the test runner:

Spin up an in-memory copy of MongoDB (no need to install MongoDB locally)
Start the Express app
Use SuperTest to send fake HTTP requests to the Express app
Run assertions — check the response and/or check what got written to MongoDB

Step 3 (SuperTest) is where things get interesting, because using it properly requires a refactor of the project structure.

6. Why a Refactor Is Needed: The `app.ts` / `index.ts` Split

The problem

SuperTest needs direct access to the Express app object to send fake requests into it. But currently, the Express app is created and started (app.listen(3000)) inside index.ts, along with:

Mongoose connecting to a hardcoded MongoDB URL
The app listening on a hardcoded port (3000)

If a test file imports the app from index.ts, it inherits all of that startup logic — including binding to port 3000.

Why hardcoded port 3000 is a real problem

You'll eventually want to run tests for multiple services at the same time on the same machine (e.g., Auth service tests running alongside Orders service tests). If both services are hardcoded to listen on port 3000, running their tests concurrently will cause a port conflict and tests will fail.

The fix: SuperTest's ephemeral port behavior

SuperTest has a built-in behavior: if the server passed to it isn't already listening on a port, SuperTest will automatically start it on a random available ("ephemeral") port.

This solves the port collision problem — but only if the Express app you hand to SuperTest isn't already bound to a fixed port.

The Solution: Split into two files

File	Responsibility
`app.ts`	Creates the Express app, wires up all middleware and route handlers, and exports the app. Does not call `.listen()` anywhere.
`index.ts`	Imports the app from `app.ts`, connects Mongoose to MongoDB, and calls `app.listen(3000)` to actually start the server for real (dev/production use).

This way:

Production/dev: you still run index.ts, which starts everything normally, including listening on port 3000.
Testing: your test files import the app directly from app.ts — no port binding, no Mongoose connection baked in — so SuperTest can safely assign it a random ephemeral port and multiple services' tests can run concurrently without colliding.

Implementation Notes (from the refactor walkthrough)

Create app.ts inside the service's source directory.
Cut all the middleware/route-wiring code out of index.ts (everything above the start function) and paste it into app.ts.
Watch out — the mongoose import might get pulled over by mistake. It needs to stay in index.ts, since that's where the DB connection actually happens.
At the bottom of app.ts, add a named export:

   export { app };

Note: curly braces are required — this is a named export, not a default export.

In index.ts, import the app at the top:

   import { app } from './app';

Save both files and verify the app still boots correctly (e.g., via Skaffold).

End result: app.ts only configures the Express app. index.ts is responsible for actually starting it (listening on a port + connecting to Mongo).

7. Installing the Test Dependencies

Three packages get installed, all as dev dependencies (--save-dev / -D flag):

npm install --save-dev @types/supertest jest supertest mongodb-memory-server

Package	Purpose
`jest`	The test runner — executes your test suite
`supertest`	Lets you make fake/simulated HTTP requests against your Express app in tests
`@types/supertest`	TypeScript type definitions for SuperTest
`mongodb-memory-server`	Spins up a temporary, in-memory MongoDB instance for tests

Why `mongodb-memory-server` instead of a real/shared MongoDB?

It lets each service's test suite run its own isolated in-memory database, rather than all services fighting over one shared test MongoDB instance.
This means multiple services' test suites can run concurrently on the same machine without interfering with each other's data.
It downloads a real copy of MongoDB (roughly ~80MB) the first time it's used, and runs it purely in memory — no local MongoDB installation required.

Why "dev dependency" matters here

The production Docker image for the service should only ever run the actual Express app — never the test suite. So none of these testing libraries need to exist inside the built Docker image.

By installing them as dev dependencies:

They get skipped when the image is built using npm install --only=production (or --omit=dev)
This avoids re-downloading the ~80MB MongoDB memory server binary every time the Docker image is rebuilt

Dockerfile change

Inside the Auth service's Dockerfile, the npm install command gets updated to only install production dependencies:

RUN npm install --only=production

This keeps rebuilds fast and avoids unnecessary bloat/downloads in the image build process — which matters a lot once you're rebuilding the image repeatedly during active development.

8. Summary — The Mental Model

Decide your test's scope first — unit → integration-within-service → component interaction → cross-service. Don't default to the broadest scope; it's expensive and complex in a microservices setup.
Test each service in isolation. Simulate cross-service behavior through event emit/receive tests rather than spinning up multiple real services together.
Focus each service's test suite on three goals: (1) request handling, (2) model behavior, (3) event emit/receive.
Run tests locally via npm run test — no Docker/Kubernetes needed for the test run itself.
Separate app creation (app.ts) from app startup (index.ts) so SuperTest can bind the app to a random port and multiple services can be tested concurrently without port conflicts.
Use mongodb-memory-server for fast, isolated, in-memory database testing — installed as a dev dependency so it never bloats the production Docker image.

Horizontal vs. Vertical Scaling: Which One Should You Actually Use?

M TOQEER ZIA — Sat, 11 Jul 2026 11:32:21 +0000

Every growing application eventually hits the same wall: the current infrastructure isn't enough. More users, more data, more requests per second — and suddenly "just add more resources" becomes a real engineering decision, not a throwaway line in a system design interview.

That decision usually comes down to two paths: scale up (vertical) or scale out (horizontal). They sound like a matter of preference, but they come with very different tradeoffs in cost, complexity, and failure modes. Let's break both down.

Vertical Scaling: Make the Machine Bigger

Vertical scaling (scaling up) means adding more power to a single machine — more CPU, more RAM, faster disks (e.g., moving from SSD to NVMe).

Before: 4 vCPU, 16GB RAM
After:  16 vCPU, 64GB RAM

On most cloud providers, this is often as simple as changing an instance type and restarting.

Example (AWS EC2):

# Stop the instance
aws ec2 stop-instances --instance-ids i-0123456789abcdef0

# Resize
aws ec2 modify-instance-attribute \
  --instance-id i-0123456789abcdef0 \
  --instance-type "{\"Value\": \"m5.2xlarge\"}"

# Start it back up
aws ec2 start-instances --instance-ids i-0123456789abcdef0

Pros

Simple. No architecture changes, no distributed systems complexity.
No data consistency issues. One machine, one source of truth.
Great for stateful workloads like traditional relational databases that aren't built for sharding.

Cons

Hard ceiling. Eventually you hit the biggest instance type available.
Single point of failure. If that one machine goes down, everything goes down.
Downtime during resize, in most setups.
Cost grows non-linearly — bigger machines get disproportionately more expensive.

Horizontal Scaling: Add More Machines

Horizontal scaling (scaling out) means adding more instances of your application and distributing load across them, typically behind a load balancer.

Before: 1 server handling all traffic
After:  5 servers behind a load balancer, each handling ~20%

Example (Docker Compose, scaling a service):

docker compose up --scale web=5 -d

Example (Kubernetes, via Horizontal Pod Autoscaler):

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web-app
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

Pros

No practical ceiling. Add as many nodes as your budget and architecture allow.
Better fault tolerance. One node dying doesn't take down the whole system.
Elastic cost. Scale down during low traffic, scale up during peaks — pay for what you use.
Enables rolling deployments with zero downtime.

Cons

Requires stateless design (or careful state management via shared caches, sessions stores like Redis, etc.).
Distributed systems problems appear: data consistency, network latency, race conditions.
More moving parts: load balancers, service discovery, health checks, orchestration.
Debugging is harder — logs and traces are spread across many nodes.

Side-by-Side Comparison

	Vertical Scaling	Horizontal Scaling
Complexity	Low	Higher (distributed systems)
Upper limit	Hardware ceiling	Practically unlimited
Fault tolerance	Single point of failure	Resilient to node failure
Cost curve	Non-linear, gets expensive fast	More linear, elastic
Downtime to scale	Usually yes	No (add/remove nodes live)
Best fit	Traditional RDBMS, legacy monoliths	Stateless services, microservices, web APIs

So Which One Should You Pick?

In practice, most real systems use both, applied to different layers:

Application/API layer → horizontal scaling. Stateless services behind a load balancer scale out cleanly and give you fault tolerance for free.
Database layer → often vertical scaling first (bigger instance, more RAM for caching, faster disks), because re-architecting for horizontal scaling (sharding, read replicas, distributed databases like CockroachDB or Cassandra) is a much bigger investment.
Cache layer (Redis, Memcached) → horizontal scaling via clustering once a single node's memory becomes the bottleneck.

A common growth path looks like this:

Start on a single small server (nothing to scale yet).
Hit load limits → scale vertically (bigger box). Fastest fix, buys time.
Vertical scaling gets expensive or hits a ceiling → move to horizontal scaling for the application tier.
Database becomes the bottleneck → introduce read replicas, then sharding or a distributed database if needed.

The Real Takeaway

Vertical scaling buys you time with minimal complexity. Horizontal scaling buys you resilience and (near) unlimited growth at the cost of architectural complexity. Neither is "better" — the right call depends on where your current bottleneck actually is, how stateful your system is, and how much complexity your team can realistically operate.

If you're not sure which one you need right now: profile first. Find out whether you're CPU-bound, memory-bound, I/O-bound, or connection-bound before reaching for either solution. Scaling the wrong dimension just gets you the same problem with a bigger bill.

Have you had to make this call in production? What tipped the decision one way or the other for you — cost, team size, or the nature of the workload? Drop it in the comments.

Load Balancing Explained: The Complete Guide to Types and Algorithms

M TOQEER ZIA — Sat, 11 Jul 2026 11:27:34 +0000

If you've ever wondered how sites like Amazon or Netflix handle millions of simultaneous users without crashing, the answer usually starts with one unsung hero of system design: the load balancer.

In this article, we'll break down what load balancing is, why it matters, and the different types and algorithms you'll encounter in real-world architectures.

What Is Load Balancing?

Load balancing is the process of distributing incoming network traffic across multiple servers so that no single server becomes overwhelmed. Instead of one server handling every request, a load balancer sits in front of a group of servers (often called a server pool or server farm) and routes each incoming request to the server best equipped to handle it.

Think of it like a checkout line at a grocery store. If everyone lines up at one register, that cashier gets overwhelmed while others sit idle. A good store manager (the load balancer) directs customers to open registers, keeping the whole line moving smoothly.

Why Load Balancing Matters

High availability – if one server fails, traffic is automatically rerouted to healthy servers
Scalability – you can add or remove servers based on demand without downtime
Performance – requests are distributed efficiently, reducing latency
Redundancy – protects against a single point of failure
Flexibility – enables maintenance and deployments without taking the whole system offline

How a Load Balancer Works

At a high level, a load balancer:

Receives an incoming client request
Checks the health/status of servers in the pool
Applies a routing algorithm to pick a server
Forwards the request to that server
Returns the response back to the client

Most load balancers also perform continuous health checks, pinging servers periodically to make sure they're still responsive before sending traffic their way.

Types of Load Balancers

1. Hardware Load Balancers

These are dedicated physical devices designed specifically to distribute traffic. They offer strong performance and reliability but come with a high upfront cost and limited flexibility. Common in large enterprises with strict compliance or performance requirements.

Pros: High throughput, dedicated resources, vendor support
Cons: Expensive, less flexible, harder to scale dynamically

2. Software Load Balancers

These run as applications on standard servers or virtual machines (e.g., NGINX, HAProxy, Traefik). They're cheaper, easier to configure, and integrate well with cloud-native and containerized environments.

Pros: Cost-effective, flexible, easy to automate
Cons: Shares resources with the host machine, may need tuning for extreme scale

3. Cloud-Based / Managed Load Balancers

Services like AWS Elastic Load Balancer (ELB), Google Cloud Load Balancing, and Azure Load Balancer are fully managed offerings. They scale automatically and integrate tightly with other cloud services.

Pros: Auto-scaling, minimal maintenance, pay-as-you-go
Cons: Vendor lock-in, less low-level control

Load Balancing by OSI Layer

Layer 4 (Transport Layer) Load Balancing

Operates at the transport layer, making routing decisions based on IP address and TCP/UDP port information — without inspecting the actual content of the packet.

Faster since it doesn't need to parse application data
Doesn't understand HTTP headers, cookies, or URLs
Good for simple, high-throughput scenarios

Layer 7 (Application Layer) Load Balancing

Operates at the application layer, meaning it can inspect the actual content of requests — HTTP headers, URLs, cookies, and even request bodies.

Enables smart routing, like sending /api/* requests to one set of servers and /images/* to another
Supports SSL termination, content-based routing, and session persistence
Slightly slower than Layer 4 due to deeper packet inspection

Common Load Balancing Algorithms

The algorithm determines how the load balancer chooses which server gets the next request.

1. Round Robin

Requests are distributed sequentially across the server pool, one after another. Simple and effective when all servers have similar capacity.

2. Weighted Round Robin

Similar to round robin, but servers are assigned weights based on their capacity. More powerful servers receive a proportionally larger share of traffic.

3. Least Connections

Routes traffic to the server with the fewest active connections. Ideal when requests vary significantly in processing time.

4. Weighted Least Connections

Combines the "least connections" logic with server capacity weighting — factoring in both current load and server power.

5. IP Hash

Uses the client's IP address to consistently route them to the same server, useful for maintaining session persistence without needing a shared session store.

6. Least Response Time

Sends traffic to the server with the fastest response time and fewest active connections, optimizing for speed.

7. Random / Random with Two Choices

Requests are distributed randomly, sometimes with a "power of two choices" optimization where the balancer picks the less-loaded of two randomly selected servers.

Global Server Load Balancing (GSLB)

Beyond distributing traffic across servers in one data center, GSLB distributes traffic across multiple data centers or geographic regions. This is essential for:

Reducing latency by routing users to the nearest region
Disaster recovery if an entire region goes down
Compliance with data residency requirements

Load Balancing vs. Reverse Proxy

These terms are often confused. A reverse proxy sits in front of servers and forwards client requests, but its primary job may be caching, SSL termination, or security — not necessarily distributing traffic across multiple backend servers. A load balancer is specifically focused on distributing traffic to prevent overload. In practice, many tools (like NGINX and HAProxy) can act as both.

Choosing the Right Load Balancer

Consideration	Recommendation
Simple traffic distribution	Round Robin or Least Connections
Session persistence needed	IP Hash or Layer 7 with sticky sessions
Mixed server capacities	Weighted Round Robin
Content-based routing	Layer 7 load balancer
Global user base	GSLB with regional data centers
Cloud-native infrastructure	Managed cloud load balancer (ELB, GCP LB, etc.)

Final Thoughts

Load balancing is a foundational concept in building scalable, resilient systems. Whether you're running a small side project or architecting infrastructure for millions of users, understanding these types and algorithms helps you make informed decisions about reliability and performance.

The right choice ultimately depends on your traffic patterns, infrastructure, and business requirements — there's no one-size-fits-all solution, but now you have the vocabulary and mental model to reason through it.

Found this useful? Feel free to share your own load balancing setups or war stories in the comments!

The New HTTP QUERY Method: Why It Exists and What Problem It Actually Solves

M TOQEER ZIA — Fri, 10 Jul 2026 19:36:50 +0000

If you've spent any time building backend systems, you know the HTTP verbs by heart: GET, POST, PUT, PATCH, DELETE. For decades, that list felt complete. Recently, though, a new method has entered the conversation — QUERY. Before diving into what it does, it's worth understanding why it was needed in the first place, because the reasoning tells you a lot about how the web actually works under the hood.

HTTP Isn't a Network Protocol — It's an Agreement

A common misconception is that HTTP is a network-level protocol like TCP or UDP. It isn't. HTTP sits at the application layer, built on top of TCP, which handles the actual transport of data between machines.

Here's the thing about TCP: it doesn't care what you send. You could open a TCP connection between two machines and transmit the string "hello," and it would arrive just fine. But that string carries no meaning. Is it a greeting? A command? Data to be saved? TCP has no concept of intent — it just moves bytes from one point to another.

This is the exact problem HTTP was designed to solve. Instead of every developer sending arbitrary, unstructured strings across the wire, HTTP introduced a standardized way to express intent. That's really what an HTTP method is: a declaration of what you're trying to do.

GET → I intend to retrieve something
POST → I intend to create something
PUT → I intend to replace something
PATCH → I intend to partially update something
DELETE → I intend to remove something

After the method comes the resource name (like /users), and after that, optional extras — headers (key-value metadata) and a body (the actual payload). This simple structure is what allows every server and client in the world, regardless of who built them, to understand each other.

Where GET Requests Start to Break Down

GET requests carry their parameters in the URL itself, using query strings — anything after the ?. This works beautifully for simple filtering: /users?name=piyush is clean, readable, and easy to reason about.

The trouble starts when your filtering needs grow. Real-world applications often need to combine multiple conditions — filter by name, restrict by age, match an email domain, sort, paginate, and more, all in a single request. Try to cram that into a query string and you run into real constraints:

URL length limits. Most browsers and servers cap URLs around 8,000 characters. Complex filters can blow past that.
Encoding overhead. Spaces and special characters aren't allowed raw in URLs — everything needs to go through encodeURIComponent or similar, making complex queries messy and error-prone.
Exposure in logs. Since query parameters live in the URL, they show up in server logs, browser history, and proxy logs — not ideal if any of that data is sensitive.

The Workaround Everyone Used (and Why It Was Broken)

Faced with these limits, developers found a workaround: if GET can't hold a complex query, just use POST instead. A POST request has a body, and a body can hold arbitrarily complex, structured JSON — filters, search terms, nested conditions, whatever you need, with no length restrictions and no awkward encoding.

So teams started building endpoints like POST /getUsers, reading the filter criteria from request.body, and running the query on the backend. Functionally, it worked. But it broke the semantic contract of REST.

The resource name says "get users." The method says "I intend to create something." That mismatch isn't just a style nitpick — it has real technical consequences:

POST requests are never cacheable. Caching systems (whether at the CDN layer or elsewhere) assume that identical POST requests might produce different side effects each time, so they're excluded from caching by default.
POST requests are not idempotent. Idempotency means that calling an operation repeatedly with the same input produces the same result every time. GET is naturally idempotent — calling GET /users/1 a thousand times returns the same user a thousand times, with no side effects. POST is the opposite: call POST /users five times with the same payload, and you'll likely end up with five different records, because POST's entire purpose is to create something new each time.

So the "use POST for complex reads" trick solved the encoding problem but created a caching and correctness problem. You couldn't cache these disguised read operations at all, even though they were, semantically, just reads.

Enter the QUERY Method

This is precisely the gap the new HTTP QUERY method fills. Conceptually, it's simple: QUERY behaves like GET — safe, cacheable, and idempotent — but it allows a request body, just like POST.

That combination is exactly what was missing. With QUERY:

Your intent is unambiguous: you're reading data, not creating or mutating it.
You can send arbitrarily complex filter logic in the request body — no URL length limits, no manual encoding gymnastics.
Because the method itself signals "this is a safe, repeatable read," CDNs and caching layers can treat QUERY requests as cacheable, the same way they treat GET.
Because it's idempotent, retry logic, deduplication, and other reliability patterns that depend on idempotency all work correctly.

In short, QUERY resolves a long-standing architectural tension between GET and POST — the need for expressive, complex read requests without sacrificing cacheability or correctness.

When Should You Actually Use It?

This doesn't mean GET is obsolete. For simple lookups and filters — a handful of query parameters — GET with query strings remains perfectly fine and arguably more transparent, since the full request is visible in the URL itself.

QUERY becomes the better choice when your read operations get complex enough that expressing them in a URL is impractical: multi-field search, nested filters, large parameter sets, or anything that previously would have forced you into the POST workaround.

The Bigger Lesson

It's worth remembering that REST conventions — GET fetches, POST creates, PUT updates — aren't laws of physics. They're self-imposed rules the developer community agreed on to keep systems interoperable. Nothing stops your server from working if you send data with a method named "hello" instead of GET. The value of these conventions is entirely in the shared understanding they create between client, server, and every piece of infrastructure (caches, proxies, logging tools) sitting in between.

The QUERY method is a good example of how these conventions evolve: not by breaking the system, but by formalizing a pattern developers were already reaching for through workarounds, and giving it the semantics it always should have had.

Building a Microservices App with Kubernetes: What I Learned the Hard Way

M TOQEER ZIA — Tue, 07 Jul 2026 12:52:32 +0000

From Docker to Minikube, Ingress, Services, and Skaffold in one real project

Introduction

I did not learn Kubernetes by reading theory alone. I learned it by building a real microservices app, breaking things, fixing them, and slowly seeing how all the parts fit together.

The project was a simple blogging app with posts and comments, but the architecture behind it was the real lesson. Instead of putting everything into one big backend, I split the app into small services: Posts, Comments, Moderation, Query, and an Event Bus. The frontend was a React client. Each service had one clear job. That choice forced me to understand containers, service discovery, deployments, networking, ingress, and local Kubernetes with Minikube.

This is my learning journey written in simple English. I am sharing what I built, why I built it this way, what confused me, and what finally made the whole picture click.

Introduction to the Project
Understanding Containers
Kubernetes Basics
Kubernetes Architecture
Deployments
Services
Load Balancing
Communication Between Microservices
Ingress Controller
Host File Configuration
Minikube
Minikube IP
Docker Inside Minikube
Skaffold
Important Commands Explained
Common Problems I Faced
Pros and Cons
Lessons I Learned
Best Practices
Conclusion
What’s Next?
SEO Details

1. Introduction to the Project

What is this project?

I built a small blogging app where users can create posts and add comments. The interesting part is not the app idea itself. The interesting part is how the app behaves behind the scenes.

The system is split into multiple services:

Posts Service creates posts
Comments Service creates comments
Moderation Service checks comments and approves or rejects them
Query Service keeps a read-optimized view for the UI
Event Bus forwards events between services
React Client shows the user interface

This project helped me understand event-driven microservices, CQRS, and eventual consistency. In simple words, one service does not try to do everything. Instead, each service does one thing well and talks to others through events.

Why microservices?

I asked myself a very practical question: why not just build one backend?

The answer became clearer as the project grew. A monolithic app is easier at the beginning, but it can become heavy later. Every change affects the same codebase and one bug can slow down the whole system.

Microservices solved a few real problems for me:

Each service could be built and understood separately
Each service could be deployed separately
One slow service did not need to block the others
It was easier to model real business flow as events
I could practice service-to-service communication the way larger systems do it

Why not a monolithic application?

I did think about a monolith first. For a small demo, that would have been simpler. But my goal was learning, not just shipping the shortest possible code.

If I had used one monolith, I would have missed the hard but useful parts:

How services discover each other
How Kubernetes manages containers
Why ingress matters
Why internal services use ClusterIP
How async events keep the system flexible

So I chose the harder path because it taught me more.

What problems microservices solve

Microservices help when different parts of an application need to move at different speeds.

For example, in my project:

Posts are created quickly
Comments may need moderation
The UI reads from a separate query model
The system should not freeze just because one service is busy

That is the kind of problem microservices handle well.

Architecture overview

Here is the high-level picture I worked with:

React Client
    |
    v
Ingress
    |
    +------------------------+
    |                        |
    v                        v
Posts Service           Query Service
    |                        ^
    v                        |
Event Bus --------------> Moderation Service
    |
    v
Comments Service

The flow is event-based. A request starts in the client, goes to a service, and then that service emits an event to the event bus. The event bus shares that event with the other services that care about it.

That separation was one of the most useful lessons in the whole journey.

2. Understanding Containers

What is Docker?

Docker was my entry point into this whole path. Before Docker, I used to think, “Why does an app work on my machine but fail somewhere else?” Docker made that question smaller.

Docker lets me package an application with everything it needs to run: code, runtime, dependencies, and configuration. That package is called an image. When the image runs, it becomes a container.

Why containers exist

Containers exist because software environments are messy.

One machine may have Node.js 16. Another may have Node.js 20. One machine may have missing packages. Another may have a different operating system. Containers reduce that problem by giving the app a predictable environment.

The easiest way I understood it was this:

An image is the blueprint
A container is the running house built from that blueprint

Images vs containers

This confused me at first, so I kept it simple.

Image: the saved template
Container: the live running instance

If I build the same image ten times, I get ten containers. They all come from the same starting point, but each container runs separately.

Why Kubernetes needs Docker

Strictly speaking, Kubernetes does not require Docker specifically anymore, but in my learning path Docker was the tool that built the container images Kubernetes used.

Kubernetes does not care how the image was built. It cares that the image exists and can be pulled by a node. Docker helped me create those images in a familiar way.

How containers communicate

In the project, containers communicate over the network. Each service listens on a port, and other services call that port using HTTP.

For example:

Posts Service listens on port 8000
Comments Service listens on port 8001
Query Service listens on port 8002
Moderation Service listens on port 8003
Event Bus listens on port 5000

One service sends a request to another service using its network address and port. That is simple in theory, but in Kubernetes it becomes easier when we use Services and DNS names instead of raw IP addresses.

Simple example

If I want the Posts Service to send an event, it posts to the Event Bus endpoint:

Posts Service -> http://event-bus-srv:5000/events

That internal address is much better than hardcoding a Pod IP, because Pods can change.

3. Kubernetes Basics

What is Kubernetes?

Kubernetes is a system that helps me run containers across one or more machines. It handles placement, restarts, scaling, and networking.

The easiest way I can describe it is this: Docker runs containers, but Kubernetes organizes them.

Why Kubernetes exists

I used to think Kubernetes was just a fancy way to run Docker. It is not.

It exists because running one container is easy, but running many containers reliably is hard. Once I had more than one service, I started asking real orchestration questions:

What if a container dies?
What if traffic increases?
Which machine should run which container?
How do services find each other?
How do I update a service without breaking everything?

Kubernetes helps answer those questions.

What problems Kubernetes solves

Kubernetes solves a few practical problems:

It restarts failed containers
It spreads containers across nodes
It scales applications up and down
It gives containers stable network identities through Services
It supports rolling updates
It makes local and production setups more similar

Cluster

A cluster is the whole Kubernetes environment. It is the group of machines that work together.

I like to think of it like a small company. The company is the cluster. Inside it, there are different employees doing different jobs.

Node

A node is one machine inside the cluster. It is where Pods run.

If the cluster is the company, the node is one office building.

Master Node or Control Plane

The master node, also called the control plane, is the brain of Kubernetes.

It decides:

Which node gets a Pod
What happens when a Pod dies
When replicas should be created or removed
How the cluster stays in the desired state

I do not normally run my app there. I let it manage the app.

Worker Node

Worker nodes are the machines that actually run my Pods and containers.

If the control plane is the manager, worker nodes are the people doing the actual work.

Pod

A Pod is the smallest deployable unit in Kubernetes.

This was one of my biggest mental shifts. Kubernetes does not usually run a raw container directly. It runs a Pod, and the Pod contains one or more containers.

I usually used one container per Pod in this project.

Container inside a Pod

A container inside a Pod is the actual process running my app.

The Pod gives it networking and shared storage if needed. The container is still the thing running Node.js or React.

Replica

A replica is another copy of the same Pod.

If one Pod is not enough to handle traffic, Kubernetes can run two, three, or more copies. That helped me understand scaling in a very simple way.

Namespace

A namespace is a way to separate resources inside the same cluster.

I think of it like separate rooms inside the same building. Everything is still inside the cluster, but the rooms help keep things organized.

Service

A Service gives Pods a stable network identity.

This matters because Pods can come and go. If I try to talk to a Pod directly, the address may change. A Service gives me one stable name and forwards traffic to the matching Pods.

That idea became very important later when I explained ClusterIP and internal service communication.

4. Kubernetes Architecture

Once I understood the pieces, I needed to understand how they connect.

Internet
   |
   v
Ingress Controller
   |
   v
Service
   |
   v
Pod
   |
   v
Container

How the connection works

The request usually starts from the browser.

The browser sends traffic to a host name such as posts.com
The Ingress Controller receives the request
Ingress routes the request to the correct Service
The Service finds a matching Pod
The Pod forwards the traffic to the container running the app

That chain is what made Kubernetes feel real to me. It is not random. It is a path.

A larger picture

                  +----------------------+
                  |   Kubernetes Cluster |
                  +----------+-----------+
                             |
           +-----------------+-----------------+
           |                                   |
           v                                   v
     Worker Node 1                        Worker Node 2
           |                                   |
        Pod(s)                              Pod(s)
           |                                   |
      Container(s)                       Container(s)

The cluster decides where the Pods go. The nodes run them. Services give access to them. Ingress gives the outside world one entry point.

5. Deployments

Why Deployments exist

When I first saw a Deployment YAML, I wondered why I could not just create a Pod directly and stop there.

The answer is that Pods are temporary, but Deployments manage Pods for me.

A Deployment makes sure the desired number of Pod replicas exists. If a Pod dies, the Deployment creates a new one. If I want to update the app, it helps perform a rolling update.

Creating Pods the right way

I used Deployments instead of manually creating Pods because I wanted Kubernetes to manage the lifecycle.

For example, the Posts service deployment looks like this in spirit:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: posts-depl
spec:
  replicas: 1
  selector:
    matchLabels:
      app: posts
  template:
    metadata:
      labels:
        app: posts
    spec:
      containers:
        - name: posts
          image: toqeer43553/posts

What each part means

apiVersion: apps/v1 means I am using the apps API group
kind: Deployment means this object manages Pods
metadata.name gives the Deployment a name
spec.replicas: 1 asks Kubernetes to keep one Pod running
spec.selector.matchLabels tells the Deployment which Pods belong to it
spec.template is the Pod template
spec.template.metadata.labels must match the selector
spec.template.spec.containers defines the container inside the Pod
image tells Kubernetes which image to run

Replica management

If I change replicas from 1 to 3, Kubernetes should keep three Pods alive.

That is useful when traffic grows. It is also useful when I want redundancy. If one Pod crashes, the others can still serve traffic.

Rolling updates

Rolling updates mean I can replace old Pods with new ones gradually.

That is safer than shutting down everything at once.

The benefit is simple:

fewer outages
less risk
easier rollback if something breaks

Self healing

Self healing was one of the most satisfying things to watch.

If I deleted a Pod manually, the Deployment created a replacement. That taught me the meaning of “desired state.” I say what I want. Kubernetes tries to keep it true.

Scaling

Scaling becomes easy once a Deployment owns the Pods.

Instead of managing each container by hand, I can ask for more replicas and let Kubernetes handle the rest.

Why I needed Deployments in this project

I had six app components. I did not want to manually babysit each one. Deployments gave me a controlled way to run them all and recover from failures.

6. Services

Services were one of the most important concepts I learned.

Why Services exist

Pods are temporary. Their IP addresses can change. That means one service cannot safely call another by Pod IP.

A Service gives me a stable name and a stable way to reach matching Pods.

Service types

I learned four common Service types.

ClusterIP

ClusterIP is the default service type. It exposes the service only inside the cluster.

I used ClusterIP for almost all internal services in this project.

Use it when:

only other services inside Kubernetes need access
you want internal service discovery
you do not want public access

Advantages:

secure by default
stable internal address
great for microservice-to-microservice communication

Disadvantages:

not reachable directly from outside the cluster

Real example:

posts-clusterip-srv
comments-srv
query-srv
event-bus-srv
moderation-srv

NodePort

NodePort exposes a service on a port on every node.

I used it for the Posts service in the project to help with external access in some learning setups.

Use it when:

you want a simple way to access a service from outside
you are learning or prototyping

Advantages:

simple to understand
easy to test locally

Disadvantages:

less flexible than Ingress
awkward for many services
not ideal for production

LoadBalancer

LoadBalancer asks a cloud provider to create an external load balancer.

Use it when:

you are in a cloud environment
you want a public entry point with managed infrastructure

Advantages:

simple cloud integration
external traffic routing is handled for you

Disadvantages:

depends on cloud support
not very useful in a pure local Minikube setup

ExternalName

ExternalName maps a service name to an external DNS name.

Use it when:

Kubernetes needs to refer to something outside the cluster

Advantages:

simple DNS aliasing
useful for external dependencies

Disadvantages:

does not act like normal proxy routing
not good for every use case

Real examples from my project

The internal services all use ClusterIP so that one service can talk to another by name.

For example:

http://event-bus-srv:5000/events
http://comments-srv:8001/events
http://query-srv:8002/events

That was much cleaner than hardcoding IPs.

Why I chose ClusterIP for internal communication

Because the services talk to each other inside the cluster.

I did not want the browser or the public internet calling my internal moderation service directly. ClusterIP kept those services private while still making them reachable from inside the cluster.

7. Load Balancing

Why load balancing is important

If one service gets a lot of traffic, one Pod may not be enough. Load balancing spreads requests across available Pods.

That matters because it improves:

performance
reliability
availability

How Kubernetes balances traffic

When I send traffic to a Service, Kubernetes forwards it to one of the matching Pods.

If there are multiple replicas, the Service acts like a traffic distributor.

Client
  |
  v
Service
  |
  +-------> Pod 1
  +-------> Pod 2
  +-------> Pod 3

What happens if one Pod crashes

If a Pod crashes, the Deployment replaces it.

If traffic is still flowing, the Service stops sending requests to the dead Pod and keeps using the healthy ones.

That gave me a lot more confidence in Kubernetes. It was not just running containers. It was actively keeping the system alive.

Simple example

If I had three replicas of the Query service, the Service could send requests to any healthy replica.

That means users would not care which exact Pod answered. They only care that the app works.

8. Communication Between Microservices

This is where the project became interesting.

The event flow I built

Posts Service
    |
    v
Event Bus
    |
    v
Query Service

Comments Service
    |
    v
Event Bus
    |
    +-------------------+
    |                   |
    v                   v
Moderation Service   Query Service
    |
    v
Event Bus
    |
    v
Comments Service

The data does not move in a straight line like a normal form submit. It moves as events.

Why ClusterIP is used here

Because these services should talk privately inside the cluster.

The browser does not need to know where Moderation lives. The browser only talks to the public entry point. The internal services talk to each other through internal DNS names such as query-srv or event-bus-srv.

Why not use Pod IPs

Because Pod IPs are temporary.

If a Pod restarts, Kubernetes may assign a new IP. That would break hardcoded service addresses.

Using service names solves that problem.

Service discovery

Service discovery means services can find each other by name.

I did not need to ask, “What is the IP address of the Event Bus today?” I could just use the service DNS name.

That is a huge reason Kubernetes feels manageable once the basics click.

Internal DNS

Inside the cluster, a service name becomes a DNS entry.

That is why code like this works:

http://event-bus-srv:5000/events

The service name is resolved inside Kubernetes, not by my laptop’s normal DNS setup.

Example from the project

When the Posts service creates a post, it stores it locally and then sends a PostCreated event to the Event Bus.

The Event Bus forwards that event to the Query service, which updates the read model.

That is the central idea:

write side changes data
event bus shares the change
read side updates asynchronously

That is event-driven microservices in plain language.

9. Ingress Controller

Why Ingress exists

Before Ingress, each service needed its own exposure strategy.

That becomes messy fast.

Ingress gives me one external entry point and lets me route requests based on host or path.

Problems before Ingress

Without Ingress, I would have needed:

multiple NodePorts
manual routing logic outside the cluster
more open ports
a harder mental model

That is not fun once a project grows.

One entry point

Ingress lets me say:

requests to /create-post go to the Posts service
requests to /get-posts go to the Query service
requests to /post/.../comments go to the Comments service
everything else goes to the React client

Host-based routing

The host in my setup is posts.com.

That means the app can be reached by a friendly domain instead of by a raw IP and port.

Path-based routing

Path-based routing means different URL paths go to different backend services.

Here is the idea in my project:

posts.com/create-post  -> Posts Service
posts.com/get-posts    -> Query Service
posts.com/post/...     -> Comments Service
posts.com/             -> Client Service

My ingress configuration

The real Ingress manifest uses the nginx ingress class and a regex path for the comments route.

That setup lets Kubernetes route requests to the correct service without the browser needing to know internal service names.

How a request travels

Browser
  |
  v
posts.com/get-posts
  |
  v
Ingress Controller
  |
  v
query-srv
  |
  v
Query Pod
  |
  v
Response to browser

That path was one of the clearest signs that I was learning real Kubernetes networking, not just memorizing YAML.

10. Host File Configuration

Why I edited the hosts file

My browser needs to know what posts.com means.

In local development, that name does not exist on the public internet. So I had to teach my laptop to map posts.com to the Minikube IP.

Example

127.0.0.1 posts.com

Or, more commonly in Minikube setups:

<Minikube IP> posts.com

Why browsers need this

When I type a domain into the browser, the browser asks DNS where to send the request.

If the domain is only for local development, I need a manual mapping. The hosts file gives me that mapping.

What I learned

This part felt small at first, but it was very important.

If the host file is wrong, Ingress may be working perfectly and the browser will still fail. That made me realize how many layers exist between “type URL” and “see page.”

11. Minikube

What is Minikube?

Minikube is a local Kubernetes cluster.

It lets me practice Kubernetes on my own machine without needing a cloud account or a production cluster.

Why use Minikube

I used Minikube because it made learning possible.

It gave me a safe place to test things like:

Deployments
Services
Ingress
Pods
DNS
local image handling

Local Kubernetes

Minikube is Kubernetes, but small and local.

That was perfect for me because I could test, break, and retry quickly.

Cluster creation

I learned that starting a cluster is the first step before applying manifests.

minikube start

That command gives me a local cluster to work with.

Cluster deletion

When I wanted a clean restart, I could delete the cluster and create it again.

minikube delete

That saved me many times when I had a messy local state.

Status

I used status checks to make sure the cluster was healthy before blaming my YAML.

Dashboard

The Minikube dashboard helped me see what was running.

Seeing Pods, Services, and Deployments in a UI made the system much less abstract.

Accessing services

Minikube also helped me access Services through IPs and tunnel-like behavior depending on the setup.

That became especially important when I started learning NodePort, Ingress, and the hosts file.

12. Minikube IP

Why Minikube has its own IP

Minikube runs as its own local Kubernetes environment. It is not the same thing as my laptop’s localhost.

That means the cluster may have a separate IP address.

localhost vs Minikube IP

localhost means my own machine.

Minikube IP means the address where the Minikube cluster can be reached.

These are sometimes related, but they are not the same thing.

Why NodePort works

NodePort exposes a port on the node.

If I know the Minikube IP and the NodePort, I can reach the service from outside the cluster.

Why localhost sometimes works

In some setups, Minikube is close enough to my local environment that localhost can work through port forwarding or driver-specific behavior.

That made me realize there is no single universal local Kubernetes setup. The exact access path depends on the driver and cluster configuration.

Internal networking

Inside the cluster, Services and Pods talk on the internal Kubernetes network.

Outside the cluster, I need Ingress, NodePort, port forwarding, or another access method.

Simple diagram

Laptop browser
    |
    v
localhost or Minikube IP
    |
    v
NodePort / Ingress
    |
    v
Service
    |
    v
Pod
    |
    v
Container

That separation helped me understand why some URLs worked and some did not.

13. Docker Inside Minikube

How Docker works inside Minikube

This was a painful but useful lesson.

I first built images on my laptop and expected Minikube to see them automatically.

That is because Minikube often uses its own image environment.

Why images are built inside Minikube

If Kubernetes inside Minikube tries to pull an image, it needs that image to exist in a place it can access.

When I build locally, my host Docker may have the image. But Minikube’s cluster may not see it unless I either push it to a registry or build it in Minikube’s Docker environment.

Why Kubernetes cannot see local Docker images

This was one of my most confusing early mistakes.

I had the image on my machine, so I assumed Kubernetes would just use it. But the cluster is not my laptop shell. The cluster is its own environment.

That is why image visibility matters.

docker-env

The Minikube Docker environment helps me build images directly into Minikube’s image store.

The command looks like this:

eval $(minikube docker-env)

Why this helps

After running that command, my Docker CLI talks to Minikube’s Docker daemon instead of my local one.

That means when I run docker build, the image is built where Kubernetes can see it.

Simple explanation

Before:

My laptop Docker -> local image only
Minikube -> cannot see it

After:

My laptop Docker CLI -> Minikube Docker daemon -> image available to Kubernetes

What I learned

I stopped thinking of Docker as one global thing. It is really a client talking to a Docker environment.

That small realization made Minikube much easier to work with.

14. Skaffold

Skaffold was the tool that made the whole workflow feel smoother.

What problem Skaffold solves

Without Skaffold, my workflow looked like this:

edit code
 -> docker build
 -> docker push
 -> kubectl apply
 -> check rollout
 -> repeat

That is slow and annoying during development.

How Skaffold automates everything

Skaffold watches files, rebuilds images, and redeploys Kubernetes resources for me.

That means I can focus on changing code instead of repeating the same commands all day.

`skaffold dev`

This command starts a development loop.

It watches for file changes and updates the cluster.

That was huge for productivity because I could edit, save, and see changes with much less manual work.

Image rebuild

When source files change, Skaffold can rebuild the matching image.

File watching

It watches my app files so I do not have to trigger everything manually.

Sync

For some files, Skaffold can sync changes directly into a running container instead of rebuilding every time.

That makes the feedback loop faster.

Auto deployment

When images change, Skaffold applies the Kubernetes manifests again.

That closes the loop between code and cluster.

Hot reload

In practice, it feels close to hot reload for the whole stack, even though the exact behavior depends on the app and file syncing setup.

My Skaffold YAML

The config in this project defines:

the Kubernetes manifests to deploy
the local build settings
the images for client and each service
the sync rules for JavaScript files

That was a clean way to keep development repeatable.

Why Skaffold mattered so much

It reduced friction.

When a workflow gets too manual, I spend more time operating tools than learning the system. Skaffold pushed me back toward learning the app itself.

15. Important Commands Explained

This is a compact cheat sheet for the commands I kept using.

kubectl commands

kubectl get pods: shows Pods.
kubectl get services: shows Services.
kubectl get deployments: shows Deployments.
kubectl describe pod: shows Pod events.
kubectl logs: prints logs.
kubectl delete pod: removes a Pod.
kubectl apply -f: applies YAML.
kubectl delete -f: deletes YAML resources.
kubectl rollout restart: restarts a Deployment.
kubectl exec: runs a command inside a container.
kubectl port-forward: forwards a local port.
kubectl get nodes: shows cluster nodes.
kubectl get ingress: shows Ingress resources.
kubectl describe ingress: helps debug routing.

Example:

kubectl apply -f infra/k8s

Minikube commands

minikube start: starts the cluster.
minikube stop: pauses the cluster.
minikube delete: resets the cluster.
minikube ip: prints the cluster IP.
minikube dashboard: opens the dashboard.
minikube docker-env: prints Docker settings.
eval $(minikube docker-env): points my shell at Minikube Docker.

Skaffold commands

skaffold dev: starts watch mode.
skaffold run: does one build and deploy.

Docker commands

docker build: creates an image.
docker images: shows local images.
docker ps: shows running containers.
docker logs: shows container output.
docker exec: runs a command inside a container.
docker tag: renames an image.
docker push: uploads an image.

Once I knew these commands, I could move from confusion to inspection much faster.

16. Common Problems I Faced

This project taught me that Kubernetes is full of small mistakes that look big at first.

Pods not starting

Usually this happened because of an image issue, a bad manifest, or a port mismatch.

How I debugged it:

ran kubectl get pods
used kubectl describe pod
checked kubectl logs

ImagePullBackOff

This often meant Kubernetes could not find the image.

My fix was usually one of these:

build the image in Minikube Docker
make sure the image name matches the manifest
ensure the tag is correct

CrashLoopBackOff

This usually meant the container started and then crashed repeatedly.

Common causes:

app error
missing environment assumptions
wrong port
bad startup code

Service not found

This usually meant I typed the wrong service name or expected the wrong DNS name.

I learned to compare the service name in YAML with the one used in code.

Ingress not working

This happened when the ingress controller was missing, the host file was wrong, or the route path did not match.

I learned to check all three layers:

Ingress resource exists
ingress controller is running
browser hostname resolves correctly

Hosts file issues

If the host mapping was wrong, nothing else mattered.

That was a reminder that local networking issues can look like app issues.

Minikube IP changed

When the Minikube IP changed, my hosts file mapping became stale.

The fix was to run minikube ip again and update the mapping.

Docker image not updating

This happened when I changed code but the cluster kept using an old image.

The fix was usually:

rebuild the image
use Skaffold
verify Minikube Docker context

Skaffold not rebuilding

This usually meant the file sync rules were too narrow or the config did not match the file location.

I learned to check the sync paths carefully.

My debugging habit

The biggest lesson was not to guess.

I tried to inspect one layer at a time:

Is the Pod running?
Is the Service correct?
Is the Ingress correct?
Does the host file point to the right place?
Does the app log show errors?

That simple checklist saved me a lot of time.

17. Pros and Cons

Pros of Kubernetes

It keeps services running and replaces failed Pods
It supports service discovery
It works from local dev to production

Cons of Kubernetes

It has a steep learning curve
YAML can be tedious
Local setups can differ from production

Pros of Skaffold

It speeds up development
It reduces manual commands
It watches files and rebuilds automatically

Cons of Skaffold

The config can be confusing at first
Sync rules need care
It adds another tool to learn

Pros of Ingress

One entry point for many services
Clean routing by host and path

Cons of Ingress

Needs an ingress controller
Debugging can be tricky
Host and path rules must match exactly

Pros of Microservices

Clear service boundaries
Easier to scale parts separately
Better for event-driven systems

Cons of Microservices

More moving parts
More networking problems
More concepts to learn

18. Lessons I Learned

This is the part that matters most to me.

At first, Kubernetes felt like too many objects with strange names. What helped was not reading more definitions. What helped was building something real.

Once I saw the posts app create an event, then watched the query model update, then saw comments go through moderation, I started to understand why these parts exist.

The biggest mental shift was this:

Docker runs containers
Kubernetes manages them
Services make them reachable
Ingress makes them public in a controlled way
Skaffold makes development faster

I also learned that microservices are not just about splitting code. They are about splitting responsibility.

Another thing that became easier was reading YAML. At first it felt dry and repetitive, but later I saw it as a contract between me and Kubernetes.

19. Best Practices

Here are the beginner-friendly practices that helped me most.

Keep services small

Each service should have one clear job.

Use service names, not Pod IPs

Pod IPs can change. Service names are stable.

Separate write and read paths when it makes sense

The CQRS idea helped my app stay organized.

Use ClusterIP for internal services

Do not expose everything publicly.

Use Ingress for the public entry point

This keeps routing clean.

Check logs early

Logs often tell the truth faster than guesswork.

Learn the manifest one piece at a time

Do not try to memorize everything at once.

Keep your local environment clean

If Minikube becomes messy, reset it instead of fighting stale state forever.

Use Skaffold during development

It saves time and keeps the feedback loop short.

Understand the path of a request

Always ask:

Where did the request start?
Which service received it?
Which Service forwarded it?
Which Pod handled it?

That question alone will save you a lot of confusion.

20. Conclusion

I started this project wanting to learn Kubernetes. I ended up learning much more.

I learned how containers package software.

I learned how Kubernetes runs those containers across a cluster.

I learned why Deployments matter, why Services matter, why Ingress matters, and why local tools like Minikube and Skaffold make practice possible.

Most of all, I learned that Kubernetes becomes easier when it is tied to a real project.

On their own, the concepts can feel abstract. But when I used them to run a real microservices app, they started to make sense.

If you are a beginner, do not try to understand everything in one day. Build something small, break it, and repeat.

That is how the pieces connect.

21. What’s Next?

This project gave me a good base, but I know there is more to learn.

The next topics I want to study are:

ConfigMaps
Secrets
Persistent Volumes
Helm
Horizontal Pod Autoscaler
Monitoring
Logging
CI/CD
Production Kubernetes
Cloud Kubernetes such as AWS EKS, GKE, and AKS

I feel more ready for those topics now because I understand the basics from a real app, not just from theory.

SEO Details

SEO title

Building a Microservices App with Kubernetes: My Beginner-Friendly Journey Through Docker, Minikube, Ingress, and Skaffold

Meta description

A beginner-friendly story of building a microservices application with Kubernetes, covering Docker, Pods, Deployments, Services, Ingress, Minikube, Docker inside Minikube, and Skaffold in simple English.

Suggested URL slug

building-microservices-app-with-kubernetes-docker-minikube-ingress-skaffold

Suggested cover image idea

A clean illustration of a laptop connected to a Kubernetes cluster, with small boxes labeled Docker, Pods, Services, Ingress, and Skaffold, styled like a simple system map.

Kubernetes Internals Explained: From Linux Primitives to Ingress

M TOQEER ZIA — Tue, 07 Jul 2026 08:15:51 +0000

If you've ever felt like Kubernetes is a pile of magic YAML files, this article is for you. We're going to build understanding from the ground up — starting with plain Linux, moving to containers, and then climbing all the way to Pods, Nodes, Deployments, Services, and Ingress. By the end, you won't just know the names of these pieces — you'll know why they exist.

Why Start With Linux?

Kubernetes didn't invent containers. It's an orchestrator sitting on top of Linux features that already existed. If you understand the Linux primitives first, every Kubernetes concept afterward becomes "oh, that's just automating this thing I already understand" instead of new magic to memorize.

Two Linux kernel features make containers possible:

1. Namespaces — Isolation

A namespace makes a process think it's the only thing running on the machine. Linux has several kinds:

PID namespace – the process sees itself as PID 1, even though the host sees it as PID 48213.
Network namespace – gives the process its own network interfaces, IP address, and routing table, separate from the host.
Mount namespace – gives the process its own view of the filesystem (its own /).
UTS namespace – lets the process have its own hostname.
IPC namespace – isolates inter-process communication (shared memory, semaphores).
User namespace – lets a process be "root" inside the container but be an unprivileged user on the host.

A container is just a regular Linux process that has been put inside a bundle of these namespaces so it believes it's alone on the machine.

2. Control Groups (cgroups) — Resource Limits

Namespaces isolate what a process can see. Cgroups control how much it can use — CPU shares, memory limits, disk I/O, network bandwidth. This is how you can say "this container gets max 512Mi of RAM" and have the kernel actually enforce it.

Takeaway: Container = Linux process + namespaces (isolation) + cgroups (resource limits) + a filesystem bundle (the image). Nothing more mystical than that.

Container Images

An image is a read-only template for creating containers. It's built in layers — each instruction in a Dockerfile (FROM, RUN, COPY, etc.) creates a new layer stacked on top of the previous one using a union filesystem (like OverlayFS).

Layer 4: COPY . /app          <- your app code
Layer 3: RUN npm install      <- dependencies
Layer 2: RUN apt-get update   <- OS packages
Layer 1: FROM node:20-alpine  <- base OS

Why layers matter:

Layers are cached — if only your app code changes, Docker/containerd reuses the lower layers instead of rebuilding everything.
Layers are shared across images — ten images built FROM node:20-alpine share that base layer on disk instead of duplicating it.

Images live in registries (Docker Hub, GitHub Container Registry, AWS ECR, etc.). When Kubernetes needs to run a container, it pulls the image from a registry to the Node first.

Container Runtime

This is the piece that actually takes an image and turns it into a running, namespaced, cgroup-limited process. Kubernetes doesn't talk to Docker directly anymore — it talks through a standard interface called CRI (Container Runtime Interface).

The common runtime stack today:

kubelet
   │  (talks CRI protocol)
   ▼
containerd  (high-level runtime: manages images, pulls, storage)
   │
   ▼
runc  (low-level runtime: actually calls Linux syscalls to create
       namespaces/cgroups and start the process)

runc is doing the literal work we described in the Linux section: calling clone() with namespace flags, setting up cgroups, and exec()-ing your process. Everything above it is orchestration.

Pods — The Smallest Deployable Unit

Here's a question that trips people up: why doesn't Kubernetes just schedule containers directly? Why the extra layer of a "Pod"?

Answer: because real applications are often more than one process that need to share resources tightly — think of a main app container plus a logging sidecar that both need to read the same files and talk over localhost.

A Pod is a group of one or more containers that share:

The same network namespace — all containers in a Pod share one IP address and can reach each other over localhost. Container A on port 8080 and container B on port 9090 in the same Pod just call localhost:8080 / localhost:9090.
Optionally, storage volumes — a Pod can define a volume that multiple containers mount.
The same lifecycle — they're scheduled together, and they die together.

How is the shared network namespace actually implemented? Kubernetes silently creates a hidden "pause" container for every Pod. This container does nothing except hold open the network namespace. Every other container in the Pod joins that namespace instead of creating its own. That's the real implementation detail behind "Pods share networking."

Pod (shares one network namespace + IP: 10.244.1.7)
├── pause container      (holds the namespace, does nothing)
├── app container        (localhost:8080)
└── sidecar container    (localhost:9090, e.g. log shipper)

This is also why the Pod, not the container, is the atomic unit Kubernetes schedules, scales, and replaces.

Nodes — Where Pods Actually Run

A Node is a worker machine (VM or bare metal) running the components needed to host Pods. Every Node runs:

kubelet – the agent that talks to the control plane, receives instructions ("run this Pod"), and tells the container runtime to do it via CRI. It also continuously reports Pod health back up.
container runtime – containerd + runc, as covered above.
kube-proxy – maintains network rules on the Node (via iptables or IPVS) so that traffic sent to a Service IP gets routed to the correct backend Pod, even though the Pod could be on a completely different Node.

Think of the kubelet as a very obedient local supervisor: the control plane never SSHs into a Node to start something — it just updates a desired state, and kubelet on each Node notices and reconciles reality to match it.

The Control Plane — The Brain

This is the part that decides what should run where, and it's separate from the Nodes that actually run your workloads.

kube-apiserver – the front door. Every single interaction with the cluster — kubectl, the scheduler, controllers, kubelets — goes through the API server. It validates requests and is the only component that talks directly to storage.
etcd – a distributed key-value store that holds the entire cluster state (every object, every desired configuration). If etcd is healthy, the cluster's "memory" is safe.
kube-scheduler – watches for Pods with no Node assigned yet, and decides which Node they should run on, based on resource availability, affinity rules, taints/tolerations, etc.
kube-controller-manager – runs the reconciliation loops. Example: the ReplicaSet controller constantly checks "do I have 3 Pods running as declared? If not, create more."

The core pattern to internalize: you declare desired state (via YAML → API server → etcd). Controllers continuously watch for drift between desired state and actual state, and correct it. Kubernetes never "runs a command once" — it enforces a state forever.

Deployments

A Deployment is a controller that manages ReplicaSets, which in turn manage Pods.

Deployment
   └── ReplicaSet (v1)
           ├── Pod
           ├── Pod
           └── Pod

Why the extra ReplicaSet layer instead of Deployment managing Pods directly? Rolling updates. When you update the image in a Deployment, it doesn't touch existing Pods — it creates a new ReplicaSet with the new Pod template, scales it up gradually, and scales the old ReplicaSet down. This is how you get zero-downtime deploys and easy rollbacks (rolling back = pointing back at the old ReplicaSet).

Services — Solving the Pod IP Problem

Pods are mortal. They get killed and recreated constantly (crashes, scaling, node failures) — and every time, they get a new IP address. So how does anything reliably talk to "the backend"?

This is what a Service solves. A Service gets a stable virtual IP and DNS name, and uses labels and selectors to find which Pods should receive traffic.

selector:
  app: my-backend

Any Pod labeled app: my-backend automatically becomes a backend for this Service — no matter how many times those Pods get replaced. kube-proxy on every Node maintains the routing rules that make "traffic to the Service IP" actually land on one of the healthy matching Pods.

Three Service types matter most:

ClusterIP (default) – a virtual IP reachable only from inside the cluster. Good for internal service-to-service communication (e.g., frontend Pod → backend Service).
NodePort – opens a specific port (30000–32767 range) on every Node's own IP, forwarding it into the Service. Lets external traffic in via <NodeIP>:<NodePort>, but it's clunky for production (you're exposing raw node IPs and non-standard ports).
LoadBalancer – asks the cloud provider (AWS/GCP/Azure) to provision an actual external load balancer that points at the Service. This is the standard way to expose something to the internet on a cloud cluster.

Port Forwarding vs Services

kubectl port-forward pod/my-pod 8080:80 is a developer debugging tool, not a production traffic mechanism. It opens a temporary tunnel from your local machine straight to a single Pod, bypassing Services and kube-proxy entirely. The moment you kill that terminal, the connection is gone. It's for "let me poke this one Pod directly while debugging" — never how real traffic reaches your app.

Ingress — HTTP Routing at the Edge

If Services (specifically LoadBalancer) already expose things externally, why do we need Ingress too?

Problem: if you have 10 HTTP microservices, giving each one its own cloud LoadBalancer means 10 expensive external load balancers, and no shared logic for things like TLS termination, host-based routing (api.example.com vs app.example.com), or path-based routing (/users vs /orders).

Ingress is a set of routing rules — "if the request comes in for api.example.com/users, send it to the users-service ClusterIP Service." But Ingress rules alone do nothing — you need an Ingress Controller (NGINX Ingress Controller, Traefik, etc.) running as Pods in your cluster that actually reads those rules and does the routing. The Ingress Controller is usually the one component that does get a single LoadBalancer Service, and everything else flows through it.

Internet
   │
   ▼
LoadBalancer Service (1 external IP)
   │
   ▼
Ingress Controller Pods (reads Ingress rules)
   │
   ├── /users  → users-service (ClusterIP)  → users Pods
   ├── /orders → orders-service (ClusterIP) → orders Pods
   └── api.example.com → api-service (ClusterIP) → api Pods

Putting the Whole Request Path Together

Here's the full journey of one HTTP request hitting your cluster, tying every piece above together:

Request hits the cloud LoadBalancer, which forwards to the Ingress Controller Pods.
Ingress Controller reads the Ingress rules and decides which internal Service should handle this path/host.
It forwards the request to that Service's ClusterIP.
kube-proxy's iptables/IPVS rules on the Node intercept traffic to that ClusterIP and redirect it to one of the matching Pods, chosen via the Service's label selector.
Traffic lands inside the Pod's shared network namespace, reaching the actual container process — a Linux process running inside namespaces and cgroups, started by runc, pulled from an image by containerd, on instructions from the kubelet, which got that instruction from the API server, which persisted it from a Deployment you applied, which is stored durably in etcd.

That's the entire stack, front to back, in one sentence.

Closing Thoughts

Every Kubernetes concept exists to solve a concrete problem:

Problem	Kubernetes Answer
Isolate processes on Linux	namespaces + cgroups
Package an app reproducibly	container images
Actually run a container	container runtime (containerd + runc)
Group tightly-coupled containers	Pods
Run Pods somewhere	Nodes (kubelet, kube-proxy, runtime)
Decide cluster-wide state	Control plane (API server, etcd, scheduler, controllers)
Zero-downtime updates & scaling	Deployments + ReplicaSets
Stable networking to mortal Pods	Services + labels/selectors
Smart HTTP routing at the edge	Ingress + Ingress Controller

Once you see it this way, Kubernetes stops being "a huge list of YAML kinds to memorize" and becomes "a small number of real problems, each solved by one clean abstraction."

If this helped clarify things, I'll be following up with a deeper dive into Services and networking internals (ClusterIP vs NodePort vs LoadBalancer under the hood) — let me know in the comments what you'd like covered next.

Database Sharding Explained: How to Scale Your Database Like a Pro

M TOQEER ZIA — Tue, 07 Jul 2026 07:27:48 +0000

If you've ever worked on an application that grew from a handful of users to thousands—or millions—you've probably hit a point where your database starts groaning under the weight. Queries get slower. CPU spikes. Storage fills up. And no amount of indexing seems to fix it.

This is usually where database sharding enters the conversation.

In this article, we'll break down what sharding actually is, why it matters, the most common strategies used in production systems, and how to decide if (and when) your project actually needs it.

What Is Database Sharding?

Database sharding is a technique for splitting one large database into multiple smaller, independent databases called shards. Each shard holds a portion of the total data, and together, all the shards make up the complete dataset.

Think of it like a library system:

A single library holding 10 million books becomes slow to search and hard to manage.
So instead, the books get split across branches:
- Branch A → Books A–F
- Branch B → Books G–L
- Branch C → Books M–R
- Branch D → Books S–Z

Each branch only manages a fraction of the total collection, which makes browsing, searching, and organizing dramatically faster. Sharding applies this same idea to databases—except instead of book titles, we're splitting rows of data across servers.

Why Do We Need Sharding?

As an application scales, a single database server eventually runs into hard limits:

Slow query performance
High CPU and memory usage
Storage limitations
Too many concurrent users/connections

Sharding solves these problems by spreading data—and the load that comes with it—across multiple servers instead of forcing one machine to do all the work.

A Practical Example

Imagine you're running a social media platform with 100 million users.

Without sharding, everything lives on one server:

DB Server 1
------------
User 1
User 2
User 3
...
User 100,000,000

Every read, write, and query hits this same machine. Eventually, it becomes a bottleneck no matter how much you optimize.

With sharding, the data is distributed:

Shard 1 → Users 1 – 25M
Shard 2 → Users 25M – 50M
Shard 3 → Users 50M – 75M
Shard 4 → Users 75M – 100M

Now four servers share the load instead of one. Each shard only needs to handle a quarter of the traffic and storage.

Common Sharding Strategies

There's no one-size-fits-all approach to sharding. Here are the three strategies you'll encounter most often.

1. Range-Based Sharding

Data is split according to a defined range of values (like ID ranges).

Shard 1 → User IDs 1–1000
Shard 2 → User IDs 1001–2000
Shard 3 → User IDs 2001–3000

Query example:

SELECT * FROM users WHERE id = 1500;

The application already knows this record lives in Shard 2, so it routes the query there directly.

Pros:

Simple to understand and implement

Cons:

Uneven growth can cause "hot" shards—one shard may end up much larger or busier than the others

2. Hash-Based Sharding

A hash function decides which shard a piece of data belongs to.

shard = userId % 3

Example distribution:

1 % 3 = 1 → Shard 1
2 % 3 = 2 → Shard 2
3 % 3 = 0 → Shard 3
4 % 3 = 1 → Shard 1

Pros:

Distributes data evenly across shards, avoiding hotspots

Cons:

Adding or removing shards later is difficult, since it changes the hash math and can require re-shuffling large amounts of data (this is where consistent hashing usually comes in to soften the blow)

3. Geographic Sharding

Data is partitioned based on the user's region or location.

Shard Pakistan → Pakistani users
Shard USA      → American users
Shard Europe   → European users

This approach is common in global applications, since it also helps reduce latency (users are served from a shard closer to them) and can assist with data residency/compliance requirements.

How Does the Application Know Which Shard to Use?

This is handled through a shard key—a value used to determine where a specific piece of data lives.

const shard = userId % 4;

Once the shard is calculated, the application routes the query to the correct database:

if (shard === 0) {
  query(DB1);
} else if (shard === 1) {
  query(DB2);
}
// ...and so on

In real-world systems, this routing logic is often abstracted into a middleware layer or handled by the database driver/proxy itself, so individual services don't need to reimplement it everywhere.

Real-Life Example: E-Commerce Platform

Let's say you're building an e-commerce platform and want to shard your users table.

User ID
--------
1
2
3
4
...

Sharding strategy:

Shard 1 → User IDs ending in 0–4
Shard 2 → User IDs ending in 5–9

When User 1234 logs in:

1234 % 2 = 0

The request is routed to Shard 1.

Sharding vs. Replication: What's the Difference?

People often confuse sharding with replication, but they solve different problems.

Sharding	Replication
Splits data across servers	Copies the same data to multiple servers
Used for scaling writes	Used for scaling reads
Each shard holds different data	Every replica holds the same data
Increases storage capacity	Improves availability & redundancy

Sharding example:

DB1 → Users 1–1000
DB2 → Users 1001–2000

Replication example:

      Primary DB
          |
   +------+------+
   |             |
Replica 1     Replica 2

In many production systems, these two techniques are actually combined—each shard has its own set of replicas for both scalability and availability.

Interview-Ready Summary

If you're prepping for a system design interview, here's a concise way to explain it:

Database sharding is a horizontal scaling technique where data is partitioned across multiple database servers called shards. Each shard contains a subset of the data and handles part of the application's workload. Sharding improves scalability, performance, and storage capacity for large-scale systems. Common strategies include range-based, hash-based, and geographic sharding.

When Should You Actually Use Sharding?

Sharding is powerful, but it's not something you should reach for on day one. It adds real architectural complexity—cross-shard queries, distributed transactions, and rebalancing all become harder problems once you shard.

Consider sharding when:

Your database size is becoming too large for a single server
Write traffic is very high
Queries are slowing down despite indexing and optimization
Vertical scaling (more CPU/RAM) is no longer enough

Before reaching for sharding, try:

Query optimization
Better indexing
Caching layers (Redis, Memcached, etc.)
Read replicas

Sharding is typically introduced once an application reaches a large scale—think millions of users or datasets that no longer fit comfortably on one machine. Until then, simpler scaling techniques usually get you further with far less complexity.

Final Thoughts

Sharding is one of those concepts that sounds intimidating until you break it down—at its core, it's just "divide the data so no single server has to do all the work." The real challenge isn't understanding the concept, it's choosing the right shard key and strategy for your specific access patterns, and being ready for the operational complexity that comes with a distributed database layer.

If you're designing for scale, start simple, measure where your actual bottlenecks are, and only shard when you have clear evidence that you need to.

If you found this helpful, feel free to follow for more system design breakdowns!

JavaScript Under the Hood: Scope, Closures, Prototypes &

M TOQEER ZIA — Mon, 29 Jun 2026 18:02:21 +0000

A deep dive into the concepts that separate junior devs from engineers who actually understand the runtime.

Part 1: Scope and Closures

var vs let vs const — It's Not Just Syntax

Most devs learn early that let and const are "the modern way" and var is old. But the real difference runs deeper than style.

Hoisting

JavaScript hoists declarations to the top of their scope before execution. But how that hoisting behaves depends on which keyword you use.

console.log(name); // undefined (not an error!)
var name = "Toqeer";

console.log(age); // ReferenceError: Cannot access 'age' before initialization
let age = 27;

var is hoisted and initialized to undefined. So the engine sees this:

var name; // hoisted to top
console.log(name); // undefined
name = "Toqeer";

let and const are also hoisted — but they are not initialized. They exist in what's called the Temporal Dead Zone (TDZ) from the start of the block until the declaration is reached.

Temporal Dead Zone (TDZ)

{
  // TDZ for `score` starts here
  console.log(score); // ReferenceError
  let score = 100;    // TDZ ends here
}

The variable exists in the scope, the engine knows about it — but you cannot touch it yet. This is intentional. It prevents you from accidentally using a variable before it's ready.

const adds one more layer: once assigned, the binding cannot be reassigned. For objects and arrays, the reference is locked — but the contents can still mutate.

const config = { debug: false };
config.debug = true; // fine
config = {};         // TypeError: Assignment to constant variable

Scope: Function vs Block

var is function-scoped. It leaks out of blocks like if, for, while.

function checkStatus() {
  if (true) {
    var status = "active";
  }
  console.log(status); // "active" — leaked out of the if block
}

let and const are block-scoped. They stay inside {}.

function checkStatus() {
  if (true) {
    let status = "active";
  }
  console.log(status); // ReferenceError
}

This is why the classic loop bug exists:

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// Prints: 3, 3, 3

for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// Prints: 0, 1, 2

With var, there's only one i shared across all iterations. With let, each iteration gets its own block-scoped i.

Closures: One of JavaScript's Superpowers

A closure is the combination of a function and the lexical environment in which it was declared. That environment stays alive and accessible to the function — even after the outer scope that created it has finished executing.

function makeCounter() {
  let count = 0;

  return function () {
    count++;
    return count;
  };
}

const counter = makeCounter();
console.log(counter()); // 1
console.log(counter()); // 2
console.log(counter()); // 3

makeCounter has long since returned. Its execution context is gone. But count lives on — because the inner function closed over it.

How Closures Form

Every function has an associated closure, created automatically at the moment the function itself is created. This happens for every function — not just ones nested inside another function — and whether or not the function body ever references a variable from an outer scope. Nesting a function inside another simply makes the closure easy to observe, because the inner function can then reach variables in the outer function's scope that would otherwise be gone once the outer function returns. The function holds a reference to its lexical environment, not a copy of the variables in it.

Practical Uses

1. Data privacy / encapsulation:

function createBankAccount(initialBalance) {
  let balance = initialBalance;

  return {
    deposit(amount) { balance += amount; },
    withdraw(amount) { balance -= amount; },
    getBalance() { return balance; }
  };
}

const account = createBankAccount(1000);
account.deposit(500);
console.log(account.getBalance()); // 1500
// `balance` is not accessible from outside

2. Function factories:

function multiplier(factor) {
  return (number) => number * factor;
}

const double = multiplier(2);
const triple = multiplier(3);

console.log(double(5)); // 10
console.log(triple(5)); // 15

3. Memoization:

function memoize(fn) {
  const cache = {};
  return function (n) {
    if (cache[n] !== undefined) return cache[n];
    cache[n] = fn(n);
    return cache[n];
  };
}

const factorial = memoize(function f(n) {
  return n <= 1 ? 1 : n * f(n - 1);
});

IIFE — Immediately Invoked Function Expression

An IIFE is a function that runs the moment it's defined.

(function () {
  const secret = "hidden";
  console.log("Runs immediately");
})();

// `secret` is not accessible out here

The outer () wraps the function expression (makes it an expression, not a declaration), and the trailing () invokes it immediately.

Why use it?

Before ES modules and block scoping with let/const, IIFEs were the primary way to:

Create a private scope and avoid polluting the global namespace
Initialize libraries and plugins
Wrap module code

const app = (function () {
  let _privateState = 0;

  return {
    increment() { _privateState++; },
    getState() { return _privateState; }
  };
})();

app.increment();
console.log(app.getState()); // 1

Today, ES modules handle this naturally. But IIFEs still appear in bundled output and are worth understanding.

Part 2: Prototypes and Inheritance

The Prototype Chain

JavaScript is a prototype-based language. Every object has an internal link — [[Prototype]] — that points to another object. When you access a property, JavaScript first looks on the object itself, then walks up the chain.

const animal = {
  breathe() {
    return "breathing...";
  }
};

const dog = Object.create(animal);
dog.bark = function () { return "woof!"; };

console.log(dog.bark());    // "woof!" — found on dog
console.log(dog.breathe()); // "breathing..." — found on animal (via prototype)
console.log(dog.toString()); // found on Object.prototype

The chain: dog → animal → Object.prototype → null

When the end (null) is reached without finding the property, undefined is returned (or a TypeError for method calls).

Object.create and Object.getPrototypeOf

Object.create(proto) creates a new object whose prototype is proto:

const vehicleProto = {
  describe() {
    return `I am a ${this.type} with ${this.wheels} wheels`;
  }
};

const car = Object.create(vehicleProto);
car.type = "car";
car.wheels = 4;

console.log(car.describe()); // "I am a car with 4 wheels"

Object.getPrototypeOf(obj) lets you inspect the chain:

console.log(Object.getPrototypeOf(car) === vehicleProto); // true

Constructor Functions

Before ES6 classes, constructor functions were the way to create objects with shared behavior.

function Person(name, age) {
  this.name = name;
  this.age = age;
}

Person.prototype.greet = function () {
  return `Hi, I'm ${this.name}`;
};

const toqeer = new Person("Toqeer", 27);
console.log(toqeer.greet()); // "Hi, I'm Toqeer"

greet lives on Person.prototype, not on each instance — so all instances share it without duplication.

The `new` Keyword — What Actually Happens

When you call a function with new, four things happen under the hood:

1. A new empty object is created: {}
2. Its [[Prototype]] is linked to Constructor.prototype
3. `this` inside the function points to that new object
4. The function returns `this` (the new object) unless it explicitly returns another object

You can see this manually:

function myNew(Constructor, ...args) {
  const obj = Object.create(Constructor.prototype); // step 1 & 2
  const result = Constructor.apply(obj, args);      // step 3
  return result instanceof Object ? result : obj;   // step 4
}

const person = myNew(Person, "Toqeer", 27);
console.log(person.greet()); // "Hi, I'm Toqeer"

This is exactly what new does — now it's not magic.

ES6 Classes — Syntactic Sugar

Classes in JavaScript are not a new object model. They're a cleaner syntax over the same prototype mechanism.

class Animal {
  constructor(name) {
    this.name = name;
  }

  speak() {
    return `${this.name} makes a sound.`;
  }
}

class Dog extends Animal {
  speak() {
    return `${this.name} barks.`;
  }
}

const d = new Dog("Rex");
console.log(d.speak()); // "Rex barks."
console.log(d instanceof Animal); // true

Under the hood:

Animal is a constructor function
speak is added to Animal.prototype
extends sets up the prototype chain: Dog.prototype → Animal.prototype
super() calls the parent constructor

The output is identical to doing it manually with constructor functions and Object.create. Classes just make the intent clearer.

Key Differences from Constructor Functions

Feature	Constructor Function	Class
Hoisted	Yes (as `undefined`)	No (TDZ applies)
Strict mode	Optional	Always strict
Callable without `new`	Yes (bad idea)	TypeError
Inherited methods	Manual prototype chain	`extends` keyword
`super` call	Manual with `.call`	Built-in

Putting It All Together

Here's everything combined — a real-world-ish example:

class EventEmitter {
  #listeners = {};

  on(event, handler) {
    if (!this.#listeners[event]) this.#listeners[event] = [];
    this.#listeners[event].push(handler);
    return this; // for chaining
  }

  emit(event, ...args) {
    (this.#listeners[event] || []).forEach(fn => fn(...args));
  }
}

class Store extends EventEmitter {
  #state;

  constructor(initialState) {
    super();
    this.#state = initialState;
  }

  setState(newState) {
    this.#state = { ...this.#state, ...newState };
    this.emit("change", this.#state);
  }

  getState() {
    return this.#state;
  }
}

const store = new Store({ count: 0 });

store.on("change", (state) => {
  console.log("State changed:", state);
});

store.setState({ count: 1 }); // "State changed: { count: 1 }"

This uses:

Private class fields (#listeners, #state) for encapsulation — closure-like privacy at the class level
Prototype inheritance via extends
super() to call the parent constructor
Method chaining via return this

Quick Reference

Scoping Rules

var → function-scoped, hoisted and initialized to undefined
let / const → block-scoped, hoisted but in TDZ until declaration
const → block-scoped + immutable binding (contents can mutate)

Closures

Every function has a closure, formed automatically at creation time — nesting and referencing outer variables aren't required, they just make the closure observable
The function holds a reference to its lexical environment, not a copy
Useful for: encapsulation, factories, memoization, event handlers

IIFE

Runs immediately, creates isolated scope
(function() { ... })()
Less common today due to ES modules, but still found in bundled code

Prototype Chain

Every object has a [[Prototype]] link
Property lookup walks the chain until null
Object.create(proto) sets the prototype explicitly

`new` Keyword Steps

Create empty object
Link prototype to Constructor.prototype
Execute constructor with this = new object
Return the new object (unless constructor returns an object)

Classes

Syntactic sugar over prototypes
extends wires prototype chain
super() calls parent constructor
Always strict, not hoistable

Understanding these fundamentals will make you a better debugger, a better code reviewer, and a more confident engineer — whether you're writing Node.js APIs, React apps, or contributing to open source.

Drop a comment if you want me to go deeper on any of these. Happy to cover the event loop, async/await internals, or WeakMaps and memory management next.

Fine-Tuning Large Language Models: A Practical Guide

M TOQEER ZIA — Tue, 16 Jun 2026 08:59:56 +0000

What Is Fine-Tuning?

A pre-trained model learns from billions of tokens of general text. It develops broad language understanding. Fine-tuning takes that base model and trains it further on a smaller, task-specific dataset.

The result: a model that performs well on your specific use case, whether that is medical diagnosis, legal summarization, customer support, or code generation.

Fine-tuning is not training from scratch. You preserve general knowledge and adapt behavior.

How a Neural Network Learns

Before fine-tuning makes sense, you need to understand what happens inside a neural network during training.

A neural network is a system of layers. Each layer contains nodes (neurons). Each connection between nodes has a weight. These weights determine what the network outputs given any input.

At the start, weights are random. Training adjusts them so the network produces correct outputs.

Here is the full training loop:

Training Data
      ↓
Forward Pass
      ↓
Prediction
      ↓
Loss Calculation
      ↓
Backpropagation
      ↓
Gradient Calculation
      ↓
Weight Update
      ↓
Repeat
      ↓
Trained Model

Phase 1: Forward Pass

The model receives an input (a sentence, an image, a token). Data flows forward through every layer. Each neuron applies a mathematical function and passes its result to the next layer.

At the end, the model produces a prediction. For a language model, this is a probability distribution over the next token.

No learning happens here. This phase only produces output.

Phase 2: Loss Calculation

The model's prediction is compared to the correct answer. A loss function measures how wrong the prediction is.

Common loss functions:

Cross-entropy loss: used for classification and language modeling
Mean squared error: used for regression tasks

A high loss means the model is far off. A loss near zero means the prediction was close to correct.

The loss is a single number. It summarizes the error for one batch of data.

Phase 3: Backpropagation

This is where learning begins.

Backpropagation works backward through the network. It calculates how much each weight contributed to the total loss. The math tool used here is the chain rule from calculus.

Think of it as blame assignment. Each weight receives a gradient: a number that says "changing this weight by X changes the loss by Y."

A large gradient means that weight had a big effect on the error. A small gradient means it had little effect.

Phase 4: Gradient Calculation

After backpropagation, every weight in the network has a gradient.

The gradient is a vector. It points in the direction of steepest increase in loss. To reduce the loss, you move in the opposite direction.

Phase 5: Weight Update (Optimization)

An optimizer uses the gradients to update every weight.

The most basic optimizer is Stochastic Gradient Descent (SGD):

new_weight = old_weight - (learning_rate × gradient)

The learning rate controls the step size. Too large: the model overshoots. Too small: training takes too long.

Modern optimizers like Adam adjust the learning rate automatically for each weight. Adam tracks the history of gradients and adapts accordingly. It converges faster than basic SGD in most cases.

The Full Loop

One pass through the data is one epoch. Training repeats this loop thousands of times across many epochs. With each pass, the weights improve. The loss decreases. The model gets better at the task.

Types of Fine-Tuning

There are three main approaches. They differ in what gets updated during training.

1. Full Fine-Tuning

All weights in the model are updated.

You take the pre-trained model and run the training loop on your dataset. Every parameter is fair game. The optimizer adjusts all of them.

Advantages:

Maximum flexibility
Best performance ceiling for large datasets

Disadvantages:

Requires significant GPU memory (storing the model, gradients, and optimizer states for billions of parameters)
Expensive and slow
Risk of catastrophic forgetting: the model overwrites general knowledge with task-specific patterns
A 7B parameter model at full precision requires roughly 28 GB of GPU memory for weights alone, plus optimizer states

Full fine-tuning makes sense when you have large datasets and substantial compute.

2. PEFT (Parameter-Efficient Fine-Tuning)

PEFT is a family of methods. The core idea: freeze most of the model and only train a small number of parameters.

You add new, trainable components to the frozen model. Only those new components are updated. The original weights stay fixed.

This reduces:

GPU memory required (no gradients for frozen weights)
Training time
Risk of catastrophic forgetting

PEFT methods include LoRA, prefix tuning, prompt tuning, and adapter layers. LoRA is the most widely used.

3. LoRA (Low-Rank Adaptation)

LoRA is the dominant PEFT method in 2024 and 2025.

The insight behind LoRA: weight updates during fine-tuning tend to have low intrinsic rank. You do not need to update a full weight matrix. You approximate the update with two much smaller matrices.

How it works:

For a weight matrix W of size (m × n), instead of updating W directly, LoRA adds two matrices:

Matrix A: size (m × r)
Matrix B: size (r × n)

Where r is the rank, typically 4, 8, 16, or 64. You only train A and B. The product AB approximates the full weight update.

During inference, the update is merged back: W_new = W + AB

Parameter count comparison:

A weight matrix of size 4096 × 4096 has 16,777,216 parameters.
LoRA with rank 8 adds two matrices: (4096 × 8) + (8 × 4096) = 65,536 parameters.
That is a 256x reduction in trainable parameters for that layer.

Advantages:

Trains on consumer GPUs (a 7B model with LoRA fits on 8-16 GB VRAM)
Multiple LoRA adapters for different tasks, swapped at inference time
The base model stays frozen and reusable

Disadvantages:

Slightly below full fine-tuning on performance in some benchmarks
Requires choosing rank (r) and which layers to target

4. QLoRA (Quantized LoRA)

QLoRA combines quantization with LoRA. It pushes LoRA further in terms of memory efficiency.

What quantization does:

Standard model weights use 16-bit or 32-bit floating point numbers. Quantization converts them to lower precision: 8-bit, 4-bit, or even 3-bit integers.

A 7B model in 16-bit uses roughly 14 GB of memory. The same model in 4-bit uses roughly 3.5 GB.

QLoRA workflow:

Load the base model in 4-bit precision (NF4 format, designed for neural network weights)
Freeze all quantized weights
Add LoRA adapters in 16-bit precision
Train only the LoRA adapters

The gradients flow through the quantized model, through the LoRA adapters. Only the adapters are updated.

Double quantization: QLoRA applies a second round of quantization to the quantization constants themselves, saving an additional 0.5 GB on a 7B model.

Advantages:

Fine-tune a 70B model on a single 48 GB GPU
Fine-tune a 7B model on a single 8 GB consumer GPU
Performance within 1-2% of full fine-tuning on most benchmarks

Disadvantages:

Slower than LoRA (dequantization overhead during forward/backward pass)
Quantization introduces approximation errors

Comparison Table

Method	Trainable Params	VRAM (7B model)	Performance	Use Case
Full Fine-Tuning	100%	80+ GB	Highest	Large datasets, max compute
PEFT (general)	0.1 - 1%	Varies	Good	Resource-constrained
LoRA	0.1 - 1%	16-24 GB	Near full	Most fine-tuning tasks
QLoRA	0.1 - 1%	6-10 GB	Near LoRA	Consumer GPU fine-tuning

Choosing the Right Method

Start with QLoRA if you are on a single GPU with less than 24 GB VRAM. It lets you work with models up to 13B or 30B parameters.

Use LoRA if you have 24-40 GB VRAM and want faster training than QLoRA.

Use full fine-tuning if you have a multi-GPU setup, a large high-quality dataset (100k+ samples), and need maximum task performance.

Key Hyperparameters in Fine-Tuning

Learning rate: Typically much lower for fine-tuning than pre-training. Common range: 1e-5 to 3e-4. Too high and you destroy pre-trained representations.

Rank (r) in LoRA: Higher rank captures more complex updates but uses more memory. Start with 8 or 16.

LoRA alpha: Scales the LoRA update. Common setting: alpha = 2 × rank.

Epochs: Fine-tuning usually needs far fewer epochs than pre-training. 1 to 5 epochs on domain-specific data is typical.

Batch size: Larger batches give smoother gradients. Use gradient accumulation if your GPU limits batch size.

What Makes Good Fine-Tuning Data

Data quality matters more than quantity.

1,000 high-quality examples often outperform 100,000 noisy ones
Format your data to match the task: instruction-response pairs for chat models, completions for base models
Balance your dataset across categories to avoid the model over-indexing on one topic
Remove duplicates; they waste training compute and bias the model

Summary

Neural networks learn by repeating a loop: forward pass, loss calculation, backpropagation, gradient calculation, weight update. Fine-tuning runs this loop on task-specific data starting from a pre-trained model.

Full fine-tuning updates everything. PEFT methods freeze most weights. LoRA approximates weight updates with low-rank matrices. QLoRA adds quantization to push memory requirements lower.

Your choice depends on your GPU, your dataset size, and your performance target.

DEV Community: M TOQEER ZIA

NATS and NATS Streaming: From Basics to Concurrency

What is NATS?

Why use NATS?

What is NATS Streaming?

The main purpose of NATS

Publisher example

The duplicate processing problem

Queue groups fix duplicates

Ordering is the harder problem

The same problem lives everywhere

Three solutions and why each falls short

The real fix: your own version numbers

Versioning in the ticketing app

Recovery and replay: three options together

The takeaway

Understanding the Event Bus: Publishers, Subscribers, and How Events Get Heard

1. Direct calls vs. event bus

2. What's actually happening inside the bus

3. A real checkout, end to end

4. The cover — zoomed out

Quick recap

Sharding, Explained: How to Talk About It in a System Design Interview

Why Sharding Exists

What Sharding Actually Is

Choosing a Shard Key

How to Distribute Data Across Shards

The Core Challenges Sharding Introduces

Hotspots and Load Imbalance

Cross-Shard Operations

Consistency Across Shards

Bringing It Together in an Interview

Testing Microservices: Scope, Strategy, and the Auth Service Test Setup

1. Why This Matters (The Problem)

2. The Four Levels of Test Scope

Why not just always test at the biggest scope (#4)?

The Decision

3. The Three Kinds of Tests You'll Actually Write (Per Service)

Test Goal #1 — Basic Request Handling

Test Goal #2 — Model-Level Unit Tests

Test Goal #3 — Event Emitting & Receiving

Why Test Goal #3 matters long-term

4. How Tests Will Actually Be Run

The underlying assumption

A note on future complexity

5. Setting Up the Test Pipeline

6. Why a Refactor Is Needed: The app.ts / index.ts Split

The problem

Why hardcoded port 3000 is a real problem

The fix: SuperTest's ephemeral port behavior

The Solution: Split into two files

Implementation Notes (from the refactor walkthrough)

7. Installing the Test Dependencies

Why mongodb-memory-server instead of a real/shared MongoDB?

Why "dev dependency" matters here

Dockerfile change

8. Summary — The Mental Model

Horizontal vs. Vertical Scaling: Which One Should You Actually Use?

Vertical Scaling: Make the Machine Bigger

Pros

Cons

Horizontal Scaling: Add More Machines

Pros

Cons

Side-by-Side Comparison

So Which One Should You Pick?

The Real Takeaway

Load Balancing Explained: The Complete Guide to Types and Algorithms

What Is Load Balancing?

Why Load Balancing Matters

How a Load Balancer Works

Types of Load Balancers

1. Hardware Load Balancers

2. Software Load Balancers

3. Cloud-Based / Managed Load Balancers

Load Balancing by OSI Layer

Layer 4 (Transport Layer) Load Balancing

Layer 7 (Application Layer) Load Balancing

Common Load Balancing Algorithms

1. Round Robin

6. Why a Refactor Is Needed: The `app.ts` / `index.ts` Split

Why `mongodb-memory-server` instead of a real/shared MongoDB?