# esp32async/espasyncwebserver architecture

> Architecture diagram of the GitHub repository esp32async/espasyncwebserver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/esp32async/espasyncwebserver
- Repository: https://github.com/esp32async/espasyncwebserver

## Overview

##### Project type and purpose
- This is an embedded library (“ESPAsyncWebServer”) for providing an asynchronous HTTP and WebSocket server on microcontrollers (ESP32, ESP8266, RP2040/RP2350).
- It exposes non-blocking request handling, middleware, SSE (Server-Sent Events), WebSocket, JSON/MessagePack streaming, authentication, file upload/serving, etc.

##### File structure
- Top-level: configuration files (`CMakeLists.txt`, `platformio.ini`), CI workflows, examples, documentation.
- `src/`: core library modules (network glue, request/response, handlers, middleware, WebSocket, event source, JSON/MessagePack support, authentication).
- `examples/`, `idf_component_examples/`, `pioarduino_examples/`: usage samples for Arduino, ESP-IDF, PlatformIO.
- `library.json` / `library.properties`: Arduino registry metadata.

##### README insights
- Confirms it’s a library—no standalone app—built on top of an asynchronous TCP layer (`AsyncTCP`, `AsyncTCPSock`, or `RPAsyncTCP`).
- Lists features (WebSocket, SSE, file serving, rewrite, redirect, authentication, JSON, upload).
- Documents build flags and runtime tuning options for the underlying TCP queue, stack size, core affinity.

a. Main components
- Hardware platform (microcontroller / Wi-Fi chipset)
- Network stack / RTOS (LWIP/TCP, FreeRTOS tasks)
- AsyncTCP abstraction (platform-specific TCP driver)
- ESPAsyncWebServer core library modules:
– AsyncWebServer (main server manager)
– AsyncWebSocket / AsyncEventSource (real-time channels)
– Middleware pipeline (filters, CORS, auth)
– Router & Handlers (URL matching, static file, chunked response)
– Request / Response objects (parsing, headers, lifecycle)
– JSON & MessagePack serializers
– WebAuthentication module
- User application code (callbacks, business logic)
- Optional storage (SPIFFS/LittleFS for static files)
- Examples harness (demonstrates API usage)

b. Relationships & data flow
1. Client (browser or IoT client) → TCP/IP over Wi-Fi → AsyncTCP driver
2. AsyncTCP passes raw data → AsyncWebServer’s event-driven loop
3. Incoming HTTP request → parsed into WebRequest → routed through Middleware → matched to a WebHandler
4. WebHandler invokes user callback → builds WebResponse (static file, chunk, JSON, SSE, WebSocket frame)
5. WebResponse → formatted into HTTP frames → AsyncTCP sends over network
6. For long-lived channels: AsyncWebSocket / AsyncEventSource maintain state; push data asynchronously on events.

c. Architectural patterns & design principles
- Event-driven, callback-based non-blocking I/O
- Middleware pipeline for cross-cutting concerns (auth, CORS, logging)
- Modular separation: transport (TCP) vs application (HTTP, WebSocket) layers
- Pluggable serializers (ArduinoJson, MessagePack)
- Build-time configuration via CMake / PlatformIO flags

d. Key technologies & dependencies
- CMake / PlatformIO build system
- ESP-IDF or Arduino core for ESP32/ESP8266/RP2040
- AsyncTCP / AsyncTCPSock / RPAsyncTCP for non-blocking TCP
- ArduinoJson (v7) for JSON support
- FreeRTOS (task affinity, queue size tuning)
- SPIFFS / LittleFS (optional) for static file storage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients and User
    Client["Client (Browser / IoT)"]:::user
    Client -->|"TCP/IP over Wi-Fi"| AsyncTCP

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        AsyncTCP["AsyncTCP Driver\n(queue size, core affinity)"]:::infra
        RTOS["FreeRTOS & LWIP"]:::infra
        Hardware["MCU + Wi-Fi Chipset"]:::infra
    end
    AsyncTCP -->|raw data| WebServerCore
    AsyncTCP -->|sends HTTP frames| Client
    RTOS --> AsyncTCP
    Hardware --> RTOS

    %% Core Library
    subgraph "ESPAsyncWebServer Core" 
        direction TB
        WebServerCore["AsyncWebServer\n(Main Server Manager)"]:::core
        Middleware["Middleware Pipeline\n(filters, CORS, auth hooks)"]:::core
        Router["Router & Handlers\n(URL matching, static/chunked)"]:::core
        subgraph "Handlers"
            direction TB
            StaticHandler["Static/File Handler"]:::core
            ChunkHandler["Chunked Response Handler"]:::core
            SSEHandler["Server-Sent Events"]:::core
            WSHandler["WebSocket Channel"]:::core
        end
        Request["WebRequest Object"]:::core
        Response["WebResponse Object"]:::core
        subgraph "Serializers"
            direction TB
            JSONSer["JSON Serializer\n(ArduinoJson)"]:::external
            MsgPackSer["MessagePack Serializer"]:::external
        end
        Auth["WebAuthentication Module"]:::core
        Version["Library Version Info"]:::core
        Backports["Core Utilities / Backports"]:::core
    end

    %% Storage and External Dependencies
    FS["SPIFFS / LittleFS"]:::external
    ArduinoJson["ArduinoJson (v7)"]:::external

    %% User Application and Examples
    UserApp["User Application\n(registers routes, callbacks)"]:::user
    Examples["Examples (Arduino, ESP-IDF, PlatformIO)"]:::user

    %% Data Flows
    WebServerCore -->|incoming HTTP| Request
    Request -->|through| Middleware
    Middleware -->|matched| Router
    Router -->|invokes| StaticHandler
    Router -->|invokes| ChunkHandler
    Router -->|invokes| SSEHandler
    Router -->|invokes| WSHandler
    StaticHandler -->|reads| FS
    ChunkHandler -->|builds| Response
    SSEHandler -->|maintains| Response
    WSHandler -->|maintains| Response
    Request -->|parses headers| Backports
    Response -->|formats HTTP| WebServerCore
    Response -->|serializes| JSONSer
    Response -->|serializes| MsgPackSer
    Middleware -->|auth checks| Auth
    Auth -->|uses| Backports
    UserApp -->|callback| Response
    WebServerCore -->|push events| WSHandler
    WebServerCore -->|push events| SSEHandler

    %% User hooks
    UserApp -->|register| WebServerCore
    Examples -->|demonstrate| UserApp

    %% Click Events
    click WebServerCore "https://github.com/esp32async/espasyncwebserver/blob/main/src/ESPAsyncWebServer.h"
    click WebServerCore "https://github.com/esp32async/espasyncwebserver/blob/main/src/WebServer.cpp"
    click WSHandler "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncWebSocket.h"
    click WSHandler "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncWebSocket.cpp"
    click SSEHandler "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncEventSource.h"
    click SSEHandler "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncEventSource.cpp"
    click Middleware "https://github.com/esp32async/espasyncwebserver/blob/main/src/Middleware.cpp"
    click Auth "https://github.com/esp32async/espasyncwebserver/blob/main/src/WebAuthentication.h"
    click Auth "https://github.com/esp32async/espasyncwebserver/blob/main/src/WebAuthentication.cpp"
    click Router "https://github.com/esp32async/espasyncwebserver/blob/main/src/WebHandlerImpl.h"
    click Router "https://github.com/esp32async/espasyncwebserver/blob/main/src/WebHandlers.cpp"
    click ChunkHandler "https://github.com/esp32async/espasyncwebserver/blob/main/src/ChunkPrint.h"
    click ChunkHandler "https://github.com/esp32async/espasyncwebserver/blob/main/src/ChunkPrint.cpp"
    click Request "https://github.com/esp32async/espasyncwebserver/blob/main/src/WebRequest.cpp"
    click Request "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncWebHeader.h"
    click Request "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncWebHeader.cpp"
    click Response "https://github.com/esp32async/espasyncwebserver/blob/main/src/WebResponseImpl.h"
    click Response "https://github.com/esp32async/espasyncwebserver/blob/main/src/WebResponses.cpp"
    click JSONSer "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncJson.h"
    click JSONSer "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncJson.cpp"
    click MsgPackSer "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncMessagePack.h"
    click MsgPackSer "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncMessagePack.cpp"
    click Version "https://github.com/esp32async/espasyncwebserver/blob/main/src/AsyncWebServerVersion.h"
    click Backports "https://github.com/esp32async/espasyncwebserver/blob/main/src/BackPort_SHA1Builder.h"
    click Backports "https://github.com/esp32async/espasyncwebserver/blob/main/src/BackPort_SHA1Builder.cpp"

    %% Styles
    classDef infra fill:#D0E8FF,stroke:#004080
    classDef core fill:#E0FFE0,stroke:#008000
    classDef external fill:#FFE0B2,stroke:#804000
    classDef user fill:#E0E0E0,stroke:#606060
```
