Module 0 — Mental Model Reset: The Non-Blocking Ingestion Pipeline

The event loop is a single-threaded loop that continuously pulls events from the event queue and executes their callbacks. It runs forever until the queue is empty and no more I/O is registered.

┌─────────────────────────────────┐
│          Event Loop             │
│                                 │
│   while (pending events) {      │
│     event = dequeue()           │
│     event.callback(event.data)  │
│   }                             │
└─────────────────────────────────┘
         ↑              ↓
    Event Queue    I/O operations
         ↑              ↓
    Event Demultiplexer (epoll/kqueue)
         ↑              ↓
    OS Kernel       Network / Disk

The Critical Insight

When a Node.js program issues an I/O operation — a database query, a file read, an outbound HTTP request — it does not wait. It registers a callback and returns immediately. The event loop continues processing other events. When the I/O completes, the OS notifies the demultiplexer, an event is queued, and the callback eventually runs.

This means a single Node.js process can handle tens of thousands of concurrent I/O operations without proportional memory consumption, because it never allocates a dedicated thread per operation.

For a UPI payment processor, this means: 50,000 concurrent requests in various stages of processing, all being managed by a single-threaded event loop backed by the OS's non-blocking I/O primitives. Memory usage scales with the number of pending callbacks and their captured data — not with the number of threads.

---

libuv: The Layer Between Node.js and the OS

The Reactor Pattern is the concept. libuv is the implementation that makes it work across operating systems.

libuv provides:

• Event loop: the main loop that drives everything
• I/O polling: wraps epoll (Linux), kqueue (macOS), IOCP (Windows)
• Thread pool: for operations that cannot be made truly non-blocking at the OS level (some file I/O, DNS, and user-submitted CPU-bound work)
• Timers: setTimeout, setInterval, setImmediate
• Async primitives: signals, child processes, IPC

The Thread Pool: The Most Misunderstood Part

Node.js is mostly single-threaded. The event loop and your JavaScript code run on one thread. But libuv maintains a thread pool (default: 4 threads, configurable via UV_THREADPOOL_SIZE) for operations that would otherwise block the event loop.

This thread pool is used for:

• fs module operations (most file I/O on Linux is not truly async at the kernel level)
• dns.lookup() (uses getaddrinfo, a blocking POSIX call)
• crypto module operations (crypto.pbkdf2, crypto.scrypt, etc.)
• User-submitted work via worker_threads

The thread pool is finite. If you submit more blocking work than the pool can handle simultaneously, subsequent work queues up. This is a critical throughput bottleneck for blockchain applications that verify cryptographic signatures on every incoming transaction — we will examine this in detail in Module 2.

"Single-Threaded" Is a Simplification, Not a Literal Thread Count

A quick calibration before you go further: when this course (and the Node.js community generally) says Node.js is "single-threaded," it means your JavaScript executes on a single thread. The OS process backing that Node.js program is running on several threads minimum, even in a default configuration with zero workers spawned:

• 1 main thread — runs the event loop and all of your JavaScript
• 4 libuv thread pool threads (default) — handle fs, DNS, some crypto, and other blocking work described above
• Several V8 background threads — used for off-thread compilation (optimizing compiler work) and concurrent/parallel garbage collection helpers

So a "single-threaded" Node.js process is realistically 6+ OS threads at idle, before you add any worker_threads. None of those background threads ever touch your JavaScript execution — that's still confined to the one main thread, which is what the single-threaded claim is actually about. Module 1 and Module 2 will introduce more of these background threads by name (V8's concurrent compiler, GC helper threads); this isn't a contradiction of what you're learning here, it's the same model with the detail filled in.

---

The Anatomy of a Single Request Through the Stack

Let me walk through exactly what happens when a transaction payload arrives at a Node.js blockchain indexer. This pipeline is the foundation for everything else in this course.

1. [NIC] Network packet arrives at the network interface card
          ↓
2. [Kernel] OS processes TCP/IP stack, places data in socket receive buffer
          ↓
3. [epoll] OS notifies epoll that the socket has readable data
          ↓
4. [libuv] libuv's I/O poll phase detects the epoll notification
          ↓
5. [Event Queue] libuv queues a "data available" event with the socket handle
          ↓
6. [Event Loop] Event loop dequeues the event, calls the registered 'data' callback
          ↓
7. [JavaScript] Your callback runs: parse JSON, validate schema, extract fields
          ↓
8. [pg driver] You issue a database write: db.query('INSERT INTO transactions...')
               → pg driver hands this to libuv as an async socket operation
               → callback returns immediately
               → event loop continues processing other events
          ↓
9. [epoll] When the PostgreSQL server responds, epoll fires again
          ↓
10. [Event Queue] Database response queued as a new event
          ↓
11. [Event Loop] Callback runs: confirm write, send HTTP 200

Notice step 8: your JavaScript code never blocks. The database write is handed off to libuv, which submits it to the OS as a non-blocking socket operation. Your JavaScript callback returns, and the event loop immediately processes the next available event — which might be another incoming transaction, another database response, or a timer callback.

This is how a single Node.js process handles 5,000 concurrent requests, each waiting on database responses, with the CPU doing real work on each of them rather than idling in blocked threads.

---

Concurrency vs Parallelism: The Distinction That Matters

Node.js achieves concurrency — handling many things at once — without parallelism — executing multiple things simultaneously on multiple CPU cores.

For I/O-bound workloads (network requests, database queries, file reads), concurrency is sufficient. The bottleneck is not CPU computation; it's waiting for I/O. Node.js interleaves this waiting across thousands of operations efficiently.

For CPU-bound workloads (transaction signature verification, Merkle proof computation, data encryption), a single thread is a hard ceiling. This is where worker_threads and cluster enter the picture — covered in Module 6.

The practical breakdown for a blockchain indexer:

The mental model: use the event loop for I/O, offload CPU work to threads.

---

Real Throughput: The Numbers That Matter

To make this concrete, here is an illustrative comparison of throughput shape for a transaction ingestion endpoint under increasing concurrent connections.

These are not measured benchmark numbers. No specific hardware, OS, framework version, or load-testing tool is being cited here — the table below is order-of-magnitude only, meant to illustrate the shape of the degradation curve, not to serve as a benchmark result you could reproduce or cite. Real numbers depend heavily on the specific Java stack, Node.js version, database, and network conditions involved.

One more qualification: "Java (thread-per-request)" below means a traditional thread-per-request servlet container (classic Tomcat/blocking JDBC style) — not modern Java. Netty, Vert.x, and reactive stacks on the JVM are non-blocking in the same sense Node.js is, and Java 21+ virtual threads (Project Loom) specifically target this exact problem. The comparison here is about a concurrency model, not about Java as a language.

At low concurrency, both models perform similarly — I/O latency dominates. As concurrency increases, thread-per-request degrades due to memory pressure and context switching. Node.js throughput degrades gently as event queue depth increases, but doesn't fall off a cliff from threading overhead, because there is no per-connection thread.

The critical observation: Node.js at 50,000 concurrent connections uses approximately the same memory as at 1,000 connections. There are no new threads. There is no new per-connection kernel structure beyond the socket and its callback state.

---

What Happens When You Block the Event Loop

The Reactor Pattern's guarantee depends on one invariant: callbacks must not block. If a callback runs a synchronous operation that takes 100ms — a long JSON parse, a synchronous file read, a tight computation loop — the event loop cannot process any other events for those 100ms.

For a payment gateway processing 10,000 req/sec, 100ms of blocking is catastrophic:

blocked time: 100ms
requests that could have been processed: 10,000 × 0.1 = 1,000 requests
result: 1,000 requests backed up in the queue, latency spike visible to users

This is called event loop starvation — and it is the single most common performance failure mode in Node.js production systems. We will measure it precisely in Module 2 using Event Loop Utilization (ELU) metrics.

For now, the first principle: anything synchronous that takes more than ~1ms must be moved off the main thread.

This includes:

• Parsing very large JSON payloads (> 1MB)
• Synchronous filesystem operations (fs.readFileSync in hot paths)
• Computationally expensive validation (complex regex, deep object traversal)
• Any crypto.*Sync operation under high load

A Preview: Backpressure as a Reactor Constraint

There's a second failure mode the Reactor Pattern introduces that's easy to miss on first read: what happens when a producer hands data to the event loop faster than a consumer can drain it? A blockchain full node can push transaction data faster than your PostgreSQL write path can absorb it. A WebSocket client can be slower to read than your indexer is to publish. In both cases, nothing is "blocked" in the sense this module has described — the event loop keeps spinning — but data queues up in memory between producer and consumer, and if nothing pushes back on the producer, that queue grows without bound until the process runs out of memory. This mismatch is called backpressure, and it is a first-class constraint of the reactor model, not an edge case: because Node.js never blocks a thread to create natural back-pressure the way a synchronous thread-per-request model sometimes does by accident, you have to design backpressure signaling deliberately. Streams in Node.js (highWaterMark, the drain event, pipe()) exist specifically to solve this. This is deep enough to be its own module — Module 4 covers it in full.

---

The Mental Model You Need to Carry Forward

By the end of this module, the following should be internalized:

Node.js does not achieve performance through parallelism. It achieves performance through eliminating idle waiting.

Thread-per-request wastes resources by allocating OS structures to connections that are mostly waiting. Node.js eliminates this waste entirely — one thread handles thousands of connections, never blocking, always doing useful work or yielding to the OS.

The constraints that follow from this model:

1. I/O is free. Thousands of concurrent network operations, database queries, and file reads cost nothing in terms of thread allocation.

2. CPU is expensive. Any computation that runs on the main thread blocks all other processing. CPU-intensive work must be offloaded.

3. The event loop is the critical path. Everything — throughput, latency, reliability — flows through this single loop. Understanding its phases, its queue structure, and its failure modes is the prerequisite for all advanced Node.js engineering.

4. libuv is not magic. It maps to real OS primitives: epoll, thread pools, timer wheels. Understanding these primitives lets you predict Node.js behavior under load, not just observe it after the fact.

---

The Working System We'll Use Throughout This Course

Every module in this course uses a concrete reference system: a live blockchain transaction indexer that ingests raw blocks from a blockchain full node, parses transactions, validates signatures, writes to PostgreSQL, and serves real-time queries via WebSocket.

This system has characteristics that stress every aspect of Node.js:

• High ingest rate: 2,000–50,000 events/second during normal to peak operation
• Cryptographic validation: every transaction requires signature verification
• Real-time consumers: WebSocket subscribers expect sub-100ms notification latency
• Durable writes: no transaction can be silently dropped
• Variable load: airdrop events, network upgrades, and market volatility create 10–50x traffic spikes with no warning

The schema we'll reference throughout:

// Transaction event arriving from blockchain full node
const transaction = {
  hash: Buffer,           // 32 bytes — raw binary
  blockHeight: BigInt,    // block number
  sender: string,         // wallet address
  recipient: string,      // wallet address (nullable for contract calls)
  amount: BigInt,         // in smallest unit (satoshi/wei/etc.)
  signature: Buffer,      // variable length, secp256k1 or ed25519
  payload: Buffer,        // raw transaction data
  timestamp: number,      // Unix milliseconds
};

Every architectural decision in the coming modules — stream processing, worker offloading, connection pooling, backpressure — will be evaluated against this system's requirements.

---

Summary

---

You now have the architectural foundation. Module 1 goes one layer deeper — into the V8 engine that executes your JavaScript, and how its compilation pipeline and garbage collector interact with sustained high-throughput ingestion.

Next: Module 1 — V8 Engine Mechanics & Zero-Allocation Ingestion →

---