# ldijkman/async-esp-fs-webserver architecture

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

- Interactive diagram: https://gitdiagram.com/ldijkman/async-esp-fs-webserver
- Repository: https://github.com/ldijkman/async-esp-fs-webserver

## Overview

##### Project type and purpose
- This is an Arduino-style library for ESP32/ESP8266 devices called “async-esp-fs-webserver.”
- Purpose: embed an asynchronous web server on the ESP, serve and edit files on its filesystem (SPIFFS/LittleFS), manage Wi-Fi credentials, support OTA firmware updates, and expose built-in web pages (/setup and /edit).

##### File structure
- Top-level
- library.properties, keywords.txt – Arduino library metadata
- platformio.ini – PlatformIO project configuration
- built-in-webpages/ – precompiled HTML/JS/CSS assets for /setup and /edit endpoints
- docs/ – published documentation, examples, and a browser-based flasher/serial monitor
- examples/ – Arduino sketches demonstrating usage (csvLogger, customHTML, remoteOTA, etc.)
- src/ – the actual library source
- src/
- AsyncFsWebServer.cpp/.h – main entrypoint of the library
- CaptivePortal.hpp, SetupConfig.hpp – Wi-Fi provisioning and options management
- edit_htm.h, setup_htm.h – C headers with embedded web page content
- ESPAsyncWebServer/ – vendored copy of the underlying asynchronous web server
- SerialLog.h, version.cpp – utility and version information

##### README for insights
- Clarifies that the library builds on ESPAsyncWebServer (Async TCP + event callbacks).
- Describes two built-in pages:
- /setup: Wi-Fi scan/selection, generic options, OTA update
- /edit: ACE-based file browser/editor for live editing of filesystem files
- Mentions mDNS for “device.local” resolution, in-browser flashing, and serial monitor.

##### Main components and interactions
a. Embedded Device (ESP32/ESP8266)
- Hardware: microcontroller, flash memory
b. Networking Stack
- AsyncTCP (ESP32) or ESPAsyncTCP (ESP8266)
- mDNS responder
- Wi-Fi manager / Captive Portal
c. Web Server Layer
- ESPAsyncWebServer – asynchronous HTTP server
- Web handlers:
– /setup handler (SetupConfig module)
– /edit handler (FsCodeEditor module)
– Static file handler for user-uploaded files & built-in assets
d. Filesystem
- SPIFFS or LittleFS
- API for read/write/delete files over HTTP
e. OTA Updater
- Web UI invoking Arduino OTA or Update API
f. Client
- Browser (Chromium-based)
– Wi-Fi provisioning UI
– ACE code editor UI
– Flashing UI (esptool-js)
– Serial monitor (WebSerialMonitor)
g. User sketch
- Calls AsyncFsWebServer.begin(), enableFsCodeEditor(), etc.
- May inject custom HTML/JS into built-in pages

##### Architectural patterns & design principles
- Event-driven, non-blocking I/O via callbacks
- Single-threaded loop with asynchronous task scheduling
- Modularization: separation between network stack, web server, filesystem, UI
- Vendored dependency isolation (embedded copy of ESPAsyncWebServer)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Browser (Client)"
        SetupUI["Setup UI"]:::ui
        CodeEditor["Code Editor"]:::ui
        Flasher["Flashing UI"]:::ui
        SerialMonitor["Serial Monitor"]:::ui
    end

    subgraph "ESP Device"
        subgraph "Networking"
            AsyncTCP["AsyncTCP/ESPAsyncTCP"]:::networking
            CaptivePortal["CaptivePortal (Wi-Fi Prov.)"]:::networking
        end
        mDNS["mDNS Responder"]:::networking

        subgraph "Web Server"
            AsyncFsWebServer["AsyncFsWebServer"]:::webserver
            ESPAsyncWebServer["ESPAsyncWebServer"]:::webserver
            SetupConfig["SetupConfig Handler"]:::webserver
            FsCodeEditor["FsCodeEditor Handler"]:::webserver
            StaticHandler["Static File Handler"]:::webserver
        end

        subgraph "Filesystem"
            SPIFFS["SPIFFS / LittleFS"]:::fs
        end

        OTA["OTA Updater"]:::ota
        UserSketch["User Sketch"]:::sketch
    end

    %% Client to Device
    SetupUI -->|HTTP Request| AsyncTCP
    CodeEditor -->|HTTP Request| AsyncTCP
    Flasher -->|HTTP Request| AsyncTCP
    SerialMonitor -->|WebSerial| AsyncTCP

    %% Networking to Web Server
    AsyncTCP -->|TCP Stream| AsyncFsWebServer
    CaptivePortal -->|Integrates with| AsyncFsWebServer
    mDNS -->|Announces| Network

    %% Web Server internals
    AsyncFsWebServer -->|wraps| ESPAsyncWebServer
    ESPAsyncWebServer -->|handles /setup| SetupConfig
    ESPAsyncWebServer -->|handles /edit| FsCodeEditor
    ESPAsyncWebServer -->|serves files| StaticHandler

    %% Web Server to Filesystem
    SetupConfig -->|read/write| SPIFFS
    FsCodeEditor -->|read/write| SPIFFS
    StaticHandler -->|serve content| SPIFFS

    %% OTA flow
    ESPAsyncWebServer -->|trigger OTA| OTA
    OTA -->|write firmware| SPIFFS

    %% Sketch integration
    UserSketch -->|calls API| AsyncFsWebServer

    %% Metadata and Examples
    subgraph "Project Files"
        Examples["examples/"]:::examples
        LibraryProps["library.properties"]:::metadata
        Keywords["keywords.txt"]:::metadata
        PlatformIO["platformio.ini"]:::metadata
    end

    %% Click Events
    click AsyncFsWebServer "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/src/AsyncFsWebServer.cpp"
    click CaptivePortal "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/src/CaptivePortal.hpp"
    click SetupConfig "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/src/SetupConfig.hpp"
    click setup_htm "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/src/setup_htm.h"
    click BuiltInSetup "https://github.com/ldijkman/async-esp-fs-webserver/tree/master/built-in-webpages/setup/"
    click edit_htm "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/src/edit_htm.h"
    click BuiltInEdit "https://github.com/ldijkman/async-esp-fs-webserver/tree/master/built-in-webpages/edit/"
    click ESPAsyncWebServer "https://github.com/ldijkman/async-esp-fs-webserver/tree/master/src/ESPAsyncWebServer/"
    click SerialLog "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/src/SerialLog.h"
    click Version "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/src/version.cpp"
    click Examples "https://github.com/ldijkman/async-esp-fs-webserver/tree/master/examples/"
    click LibraryProps "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/library.properties"
    click Keywords "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/keywords.txt"
    click PlatformIO "https://github.com/ldijkman/async-esp-fs-webserver/blob/master/platformio.ini"

    %% Styling
    classDef networking fill:#D0E8F2,stroke:#1E88E5,stroke-width:2px;
    classDef webserver fill:#DFF6DD,stroke:#43A047,stroke-width:2px;
    classDef fs fill:#FFE5B4,stroke:#FB8C00,stroke-width:2px;
    classDef ota fill:#FCE4EC,stroke:#D81B60,stroke-width:2px;
    classDef ui fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef sketch fill:#E0E0E0,stroke:#616161,stroke-width:2px;
    classDef examples fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px;
    classDef metadata fill:#F5F5F5,stroke:#9E9E9E,stroke-width:2px;
```
