‍New here? Start with the learn index. This page assumes no prior networking knowledge.

When you load a web page, an astonishing amount happens between "click" and "page appears". To keep it understandable, engineers split the work into layers. Each layer has one job, and only talks to the layer directly above and below it. This layered map is called the OSI model (Open Systems Interconnection) - seven layers, numbered 1 (closest to the hardware) to 7 (closest to you).

You do not need to memorize it. You need the intuition: a message is built up layer by layer as it leaves one computer, and taken apart layer by layer as it arrives at the other.

An analogy: sending a physical letter

Imagine mailing a birthday card to a friend in another country:

You write the card (the actual message - this is the top layer).
You put it in an envelope and write the address.
Your local post office sorts it and decides which city it goes to.
The national postal service routes it across the country / world.
A truck, plane, and mail carrier physically move it (the bottom layer - real atoms moving through space).

At the other end, the same steps happen in reverse: the carrier delivers it, your friend takes it out of the envelope, and reads the card. Each step only cares about its own job. The mail carrier does not read your card; you do not drive the truck.

Networking works exactly like this. Each layer wraps the data from the layer above (adds its own "envelope", called a header) and hands it down. This wrapping is called encapsulation.

The seven layers (top to bottom)

We will go top-down, because that is the order data is created when you send.

Layer 7 - Application

The program you actually use, and the rules it speaks. A web browser speaks HTTP; an email app speaks SMTP. This layer is about meaning: "GET me the page `/index.html`".

In this library, Layer 7 is the web server you write - your routes and handlers. Code: src/network_drivers/application/ and the public API in dwserver.h.

Layer 6 - Presentation

Turns the application's meaning into a precise sequence of bytes on the wire, and back again - the "grammar" of the conversation. Parsing an HTTP request's text into fields, framing a WebSocket message, encoding JSON: all Layer 6.

Code: src/network_drivers/presentation/ (the HTTP parser, WebSocket framing, SSE, etc.).

Layer 5 - Session

Manages the conversation itself: who is talking, starting and ending exchanges, and deciding when work happens. In this library that is the worker task that picks up incoming data and runs the right handler.

Code: src/network_drivers/session/.

Layer 4 - Transport

Delivers a reliable stream of bytes between two specific programs. Two key ideas live here:

Ports: a single computer runs many programs. A port number says which program a message is for (a web server usually listens on port 80, or 443 for the encrypted version). Think of it as the apartment number after the street address.
TCP vs UDP: TCP guarantees every byte arrives, in order, with nothing lost (like a phone call where you confirm you heard each word). UDP just fires messages off with no guarantee (like shouting across a room - fast, but some words may be missed). We cover this in detail in TCP/IP.

Code: src/network_drivers/transport/ - this is where the library owns all socket I/O.

Layer 3 - Network

Gets a message across networks - from your house to a server on the other side of the planet, hopping through many routers along the way. The hero here is the IP address (like 192.168.1.85), the unique-ish number that identifies a machine on the network. Routing is "which direction do I forward this to get it closer?".

Code: src/network_drivers/network/ (IPv4, choosing which interface - e.g. Wi-Fi station vs access point - a message goes out).

Layer 2 - Data Link

Moves data between two devices on the same local link (e.g. your laptop and your home router) and wraps it in a frame. It deals with hardware addresses (MAC addresses) and detecting garbled data on that one hop.

Code: src/network_drivers/datalink/.

Layer 1 - Physical

The actual physical thing: radio waves for Wi-Fi, electrical pulses in an Ethernet cable, light in a fiber. Pure 1s and 0s becoming real-world signals.

Code: src/network_drivers/physical/ (bringing the Wi-Fi / Ethernet hardware up and tracking whether the link is alive).

How data flows: down one side, up the other

Here is the whole journey of one web request, from a browser to this server and back. Notice how each layer adds a header going down, and removes it going up:

   BROWSER (sending)                         ESP32 SERVER (receiving)
   ----------------                          ------------------------
7  Application   "GET /temperature"      7   Application   run the /temperature handler
6  Presentation  format as HTTP bytes    6   Presentation  parse the HTTP bytes  ^
5  Session       start the exchange      5   Session       hand to a worker      |
4  Transport     [TCP header][ data ]    4   Transport     reassemble the stream |
3  Network       [IP header][  ...   ]   3   Network       check it is for us    | UP
2  Data Link     [frame][    ...      ]  2   Data Link     check this hop        |
1  Physical      radio waves  ~~~~~~~>   1   Physical      radio waves received  |
        |                                                          ^
        +------------- through routers across the internet --------+
            DOWN                                              (then back up)

Going down, the message gets wrapped in more and more headers (envelopes). Going up, each layer reads and strips off its header, then hands the rest upward. The browser's Layer 4 talks "logically" to the server's Layer 4, even though physically everything travels all the way down to Layer 1 and back up. That illusion - each layer chatting with its twin on the other machine - is the heart of the OSI model.

OSI vs reality

The OSI model is the teaching map. The internet itself runs on a simpler, 4-layer cousin called TCP/IP, which merges some OSI layers together. They describe the same reality at different zoom levels. Once the 7 layers make sense, read TCP/IP to see the version your devices actually use - and why this library still keeps the layers cleanly separated.

Why this library is built in layers

Most embedded web servers blend all of this together. This one keeps each layer in its own folder with a clean boundary, on purpose:

You can read one layer without understanding the others.
A bug usually lives in exactly one layer, so it is easier to find and fix.
You can swap a layer (say, Wi-Fi for Ethernet at Layer 1) without touching the rest.
And - for learners - the textbook diagram above is the source tree.

Next: TCP/IP: the model the internet actually uses.