> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nginx Architecture

> Explains NGINX architecture, focusing on event-driven non-blocking I/O and master worker processes that enable efficient, high concurrency handling of thousands of simultaneous connections.

This document explains why NGINX is so efficient at handling large numbers of concurrent connections. At its core is an event-driven, non-blocking architecture combined with a multi-process model for multicore systems. The explanation below preserves the original diagrams and order while improving flow and clarity.

## Overview: event-driven, non-blocking I/O

NGINX uses an event-driven (asynchronous, non-blocking) model inside each worker process. Instead of dedicating a thread or process to each connection, each worker runs an event loop that polls for readiness events (readable sockets, writable sockets, timers, etc.) and processes events as they become ready. This avoids blocking on slow I/O (disk, upstream servers, or slow clients) and allows a single worker to handle thousands of simultaneous connections with low memory and CPU overhead.

## The coffee-shop analogy

Imagine a busy coffee shop:

* If a single barista took an order, prepared the drink, and then took the next order, the line would grow.
* Instead, one person takes orders, another prepares drinks, and a third hands them out. While a drink is being prepared, the order-taker continues taking new orders.

This separation of responsibilities—decoupling the waiting work from the active work—is the essence of NGINX’s event-driven model. While a request is waiting for I/O, the worker’s event loop moves on to other ready events.

## How the event loop operates

The event loop repeatedly polls the operating system for events and dispatches ready events to handlers. On Linux NGINX typically uses `epoll`; on BSD and macOS it uses `kqueue`. Because the loop never blocks on a single connection, workers can make progress on many connections concurrently.

![A flow diagram titled "Event Handling in Nginx" showing boxes for Incoming Request → Event Loop → Processing the Event → Response Sent connected by arrows. A user icon at left sends an HTTP request to the pipeline and receives the response after processing.](https://mintcdn.com/kodekloud-c4ac6d9a/ij3FNIPjp1w0Myd0/images/Nginx-for-Beginners/Introduction/Nginx-Architecture/nginx-event-handling-flow-diagram.jpg?fit=max\&auto=format\&n=ij3FNIPjp1w0Myd0\&q=85\&s=917abb719eab3bde81271df45e84977b)

## Core steps in NGINX request processing

| Step | What happens |
| - | - |
| 1. Incoming request | NGINX accepts an HTTP(S) request from a client on a listening socket. |
| 2. Event loop (polling) | The worker records the connection and continues polling for ready events (readable/writable sockets, timers). The loop is non-blocking, so other events are processed while this request waits for I/O. |
| 3. Processing the event | When required resources are available (upstream response, file read, etc.), the worker runs the configured handlers (proxy, rewrite, cache lookup) to produce a response. |
| 4. Response sent | The response is written back to the client. The connection is then handled according to configuration (keepalive, close, etc.). |

This event-driven loop allows a single worker to multiplex many connections efficiently without creating a thread per connection.

## Scaling across CPU cores: master and worker processes

To utilize multiple CPU cores and to provide process-level isolation, NGINX runs as multiple processes:

* Master process
  * Runs with elevated privileges.
  * Loads configuration, opens listening sockets, and manages worker lifecycles (start, stop, reload).
  * Does not handle client requests directly.
* Worker processes
  * Each worker runs a single-threaded event loop.
  * Workers accept connections and handle all request processing using non-blocking I/O (epoll, kqueue, etc.).
  * Multiple workers run in parallel across cores, giving both concurrency and resilience.

Think of the master process as a supervisor who manages staffing and resources, while the workers are the chefs and servers doing the request handling.

![A diagram titled "Request Handling in Nginx" showing a single Master Process at the top delegating incoming Request/Response connections to multiple Worker Processes. Each worker contains an Event Loop that handles the requests.](https://mintcdn.com/kodekloud-c4ac6d9a/ij3FNIPjp1w0Myd0/images/Nginx-for-Beginners/Introduction/Nginx-Architecture/nginx-request-handling-master-workers-eventloop.jpg?fit=max\&auto=format\&n=ij3FNIPjp1w0Myd0\&q=85\&s=39868448fbc56e8ba19aa43176468e55)

## Why this design is efficient

* Event-driven, non-blocking I/O minimizes idle CPU and memory usage when many connections are waiting.
* A single worker can handle thousands of simultaneous connections because it relies on readiness notifications rather than blocking threads.
* Multiple worker processes provide parallelism across cores and enable graceful restarts and configuration reloads with minimal disruption.

NGINX achieves high concurrency by combining an event loop (non-blocking I/O) inside each worker with multiple worker processes to utilize multiple CPU cores. This design delivers memory-efficient, high-throughput request handling suited for modern web workloads.

## Links and references

* NGINX basics and architecture: [https://nginx.org/en/docs/](https://nginx.org/en/docs/)
* epoll (Linux): [https://man7.org/linux/man-pages/man7/epoll.7.html](https://man7.org/linux/man-pages/man7/epoll.7.html)
* kqueue (BSD / macOS): [https://man.openbsd.org/kqueue.2](https://man.openbsd.org/kqueue.2)

Thanks for your time.

> **[Watch Video](https://learn.kodekloud.com/user/courses/nginx-for-beginners/module/9e6f72d7-933d-42dd-a948-ae48d66aecb6/lesson/56033553-c70c-4935-b94a-c1c369193c0a)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.