# khoih-prog/asynchttprequest_generic architecture

> Architecture diagram of the GitHub repository khoih-prog/asynchttprequest_generic, 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/khoih-prog/asynchttprequest_generic
- Repository: https://github.com/khoih-prog/asynchttprequest_generic

## Overview

##### Project Type & Purpose
- This is an Arduino-style client library (“AsyncHTTPRequest_Generic”) that provides a non-blocking, callback-driven HTTP layer for embedded C++ applications on ESP8266, ESP32 and STM32 boards.  It wraps board-specific asynchronous TCP stacks to let user sketches issue GET/POST/PUT/etc. requests without blocking the MCU.

##### File-Structure Analysis
- Top-level
- library.json & library.properties – metadata for Arduino and PlatformIO.
- README.md – full documentation.
- LICENSE, CONTRIBUTING.md, .github/ – governance and CI.
- src/
- AsyncHTTPRequest_Generic.h/.hpp/.cpp – public C++ API and template implementation.
- AsyncHTTPRequest_Impl_Generic.h – conditional‐compile transport adapter.
- xbuf buffer classes inside.
- examples/
- One sketch per board/type demonstrating usage (ESP32, ESP8266, STM32, ENC28J60, W5500, etc.).
- multiFileProject shows best practice for avoiding multiple‐definition errors.
- Packages_Patches/
- Board-core override files for STM32, Arduino SAMD, Seeeduino, etc. to support LAN8720, Serial1, etc.
- platformio/
- platformio.ini demonstrating auto-install of dependencies.
- utils/
- Formatting scripts (astyle, restyle).

##### Key Insights from README
- Architecture: layered HTTP-on-TCP abstraction mirroring XMLHttpRequest’s ready-state model.
- Dependencies: ESPAsyncTCP (ESP8266), AsyncTCP (ESP32), STM32AsyncTCP or STM32Ethernet+LwIP for STM32.
- Principles: non-blocking callbacks (onReadyStateChange, onData), small-segment chained buffer (xbuf).
- Extensibility: pluggable transport via AsyncHTTPRequest_Impl_Generic.h; examples cover WiFiManager, SPIFFS/LittleFS.

##### Components & Interactions (
a. Main Components
1. Application Sketch (Arduino .ino)
2. AsyncHTTPRequest_Generic Library
3. Transport Adapter Layer
‑ ESPAsyncTCP adapter (ESP8266)
‑ AsyncTCP adapter (ESP32)
‑ STM32AsyncTCP / STM32Ethernet+LwIP adapter (STM32)
4. Network Interface
‑ Wi-Fi PHY / Ethernet PHY (LAN8720, LAN8742A, W5500, ENC28J60, W6100)
5. Board MCU
‑ ESP8266 / ESP32 / STM32
6. External HTTP Server (cloud/service)
7. Optional FileSystem (SPIFFS, LittleFS) for credential-store in WiFiManager examples
8. Packages_Patches Mechanism (override board core files)

b. Relationships & Data Flow
- Sketch calls AsyncHTTPRequest API →
- Library builds HTTP request, enqueues into xbuf →
- Calls Transport Adapter to open TCP connection →
- Adapter uses AsyncTCP (board-specific) →
- AsyncTCP schedules non-blocking send/receive through hardware PHY →
- Packet flows over network to External HTTP server →
- Response events flow back upward through the same chain, invoke onData/onReadyStateChange →
- Sketch processes callbacks.
- If using examples with WiFiManager: Sketch ↔ FileSystem for storing/retrieving credentials before HTTP.
- Packages_Patches interact at build time, not at runtime.

c. Architectural Patterns & Principles
- Layered Abstraction – clear separation Sketch / HTTP library / TCP stack / PHY / MCU.
- Pluggable Adapters – single “Generic” API, concrete transport bound at compile time.
- Event-Driven, Non-Blocking – callbacks for state progression, data reception.
- Chain-of-Responsibility for buffer management (xbuf segments).
- Conditional Compilation – #if defined(ESP32) / ESP8266 / STM32 in impl header.

d. Key Technologies & Frameworks
- C++ headers + template implementation (.h/.hpp) to avoid linker errors.
- AsyncTCP / ESPAsyncTCP / STM32AsyncTCP / STM32Ethernet + LwIP
- Arduino Core for ESP8266, ESP32, STM32
- SPIFFS / LittleFS (in examples)
- PlatformIO builds & dependency manager

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        Sketch["Application Sketch"]:::app
        FS["File System (SPIFFS/LittleFS)"]:::fs
    end

    %% Library Core
    subgraph "Library Core"
        CoreAPI["AsyncHTTPRequest_Generic API"]:::core
        CoreImpl["AsyncHTTPRequest_Generic Implementation"]:::core
        Debug["Debug Support"]:::core
    end

    %% Transport Adapters
    subgraph "Transport Adapters"
        Adapter["Transport Adapter (conditional)"]:::adapter
    end

    %% TCP Frameworks
    subgraph "TCP Frameworks"
        ESP8266TCP["ESPAsyncTCP (ESP8266)"]:::framework
        ESP32TCP["AsyncTCP (ESP32)"]:::framework
        STM32TCP["STM32AsyncTCP / STM32Ethernet+LwIP"]:::framework
    end

    %% Hardware PHY
    subgraph "Hardware PHY"
        PHY1["WiFi PHY"]:::phy
        PHY2["Ethernet PHY (LAN8720, W5500, etc.)"]:::phy
    end

    %% External Server
    Server["External HTTP Server"]:::external

    %% Build-time Overlays
    Packages_Patches["Packages_Patches (build-time)"]:::patch

    %% Connections - Request Flow
    Sketch -->|uses| CoreAPI
    CoreAPI -->|invokes| CoreImpl
    Sketch -->|store/retrieve creds| FS
    CoreAPI -->|builds HTTP request| Adapter
    Adapter -->|calls TCP stack| ESP8266TCP
    Adapter -->|calls TCP stack| ESP32TCP
    Adapter -->|calls TCP stack| STM32TCP
    ESP8266TCP -->|sends frame| PHY1
    ESP32TCP -->|sends frame| PHY1
    STM32TCP -->|sends frame| PHY1
    STM32TCP -->|sends frame| PHY2
    PHY1 -->|Ethernet frame| Server
    PHY2 -->|Ethernet frame| Server

    %% Connections - Response Flow
    Server -->|response/events| ESP8266TCP
    Server -->|response/events| ESP32TCP
    Server -->|response/events| STM32TCP
    ESP8266TCP -->|onData/onReadyStateChange| CoreAPI
    ESP32TCP -->|onData/onReadyStateChange| CoreAPI
    STM32TCP -->|onData/onReadyStateChange| CoreAPI
    CoreAPI -->|callback| Sketch

    %% Build-time Dependencies
    Packages_Patches -.-> Adapter
    Packages_Patches -.-> ESP8266TCP
    Packages_Patches -.-> ESP32TCP
    Packages_Patches -.-> STM32TCP

    %% Legend
    subgraph "Legend"
        L1["Core Library"]:::core
        L2["Transport Adapter"]:::adapter
        L3["TCP Framework"]:::framework
        L4["Hardware PHY"]:::phy
        L5["External Service"]:::external
        L6["Filesystem"]:::fs
        L7["Build-time Overlay"]:::patch
    end

    %% Click Events
    click Sketch "https://github.com/khoih-prog/asynchttprequest_generic/tree/master/examples/"
    click CoreAPI "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/src/AsyncHTTPRequest_Generic.h"
    click CoreImpl "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/src/AsyncHTTPRequest_Generic.hpp"
    click Adapter "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/src/AsyncHTTPRequest_Impl_Generic.h"
    click Debug "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/src/AsyncHTTPRequest_Debug_Generic.h"
    click library.json "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/library.json"
    click library.properties "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/library.properties"
    click keywords "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/keywords.txt"
    click README "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/README.md"
    click changelog "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/changelog.md"
    click .github "https://github.com/khoih-prog/asynchttprequest_generic/tree/master/.github/"
    click workflows "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/.github/workflows/auto-github-actions.yml"
    click Packages_Patches "https://github.com/khoih-prog/asynchttprequest_generic/tree/master/Packages_Patches/"
    click platformio "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/platformio/platformio.ini"
    click astyle "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/utils/astyle_library.conf"
    click restyle "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/utils/restyle.sh"
    click CONTRIBUTING "https://github.com/khoih-prog/asynchttprequest_generic/blob/master/CONTRIBUTING.md"
    click LICENSE "https://github.com/khoih-prog/asynchttprequest_generic/tree/master/LICENSE"

    %% Styles
    classDef app fill:#e3f2fd,stroke:#90caf9,color:#0d47a1;
    classDef core fill:#bbdefb,stroke:#2196f3,color:#0d47a1;
    classDef adapter fill:#c8e6c9,stroke:#4caf50,color:#1b5e20;
    classDef framework fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef phy fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef external fill:#eeeeee,stroke:#9e9e9e,color:#424242;
    classDef fs fill:#f3e5f5,stroke:#ab47bc,color:#4a148c,shape:cylinder;
    classDef patch fill:#f5f5f5,stroke:#bdbdbd,color:#616161,stroke-dasharray: 5 5;
```
