# psynyde/esp32-win98-server architecture

> Architecture diagram of the GitHub repository psynyde/esp32-win98-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/psynyde/esp32-win98-server
- Repository: https://github.com/psynyde/esp32-win98-server

## Overview

1. **Project shape**
   - This is an **ESP-IDF firmware application** for an ESP32 board, not a general server app.
   - The runtime is split between the ESP32 app code under `main/` and the ESP-IDF build/config system at the repo root.

2. **Startup and app lifecycle**
   - `main/main.c` is the firmware entrypoint (`app_main` in ESP-IDF terms).
   - It likely initializes networking, storage, and the web server in that order, then hands off control to the server loop/task model used by ESP-IDF.

3. **Web server boundary**
   - `main/server.c` / `main/server.h` form the main HTTP-serving subsystem.
   - This is the boundary where incoming browser requests are routed to:
     - static page responses,
     - the sysinfo view,
     - guestbook read/write operations.
   - The README indicates the device serves a Windows 98–styled site, so the server is a core runtime component rather than a supporting utility.

4. **Static page/content layer**
   - `main/pages/` contains the HTML pages: `about.html`, `guestbook.html`, and `sysinfo.html`.
   - `main/assets/` holds shared static resources such as styling/images/scripts.
   - The build flow copies/optimizes these into a generated `main/dist` directory before compilation, so the firmware serves prebuilt web content rather than rendering from templates at runtime.

5. **Dynamic sysinfo path**
   - The sysinfo page is a dynamic endpoint backed by ESP-IDF APIs.
   - It gathers device/runtime statistics from the ESP32 itself, then injects or serves them through the web server.
   - This is a read-only path: browser request → server handler → ESP hardware/system data → HTML response.

6. **Guestbook persistence path**
   - The guestbook is the only clearly stateful feature.
   - The README says entries are stored on **littlefs**, so the flow is: browser form submission → server handler → filesystem write → later read back for display.
   - This creates a clear separation between transient HTTP handling and durable storage on flash.

7. **Filesystem and flash layout**
   - `partitions.csv` defines the ESP32 flash layout, which must accommodate firmware plus a storage partition for littlefs.
   - That makes storage an architectural concern, not just an implementation detail: guestbook persistence depends on partitioning and flash size.
   - `sdkconfig.default` provides baseline firmware settings, with Wi-Fi credentials configured later via `menuconfig`.

8. **Shared application logic**
   - `main/core.c` / `main/core.h` look like the shared utility layer used by the app and server.
   - In a diagram, this is the “common services” block between startup and the HTTP handlers, likely containing helpers for configuration, rendering, or device-specific operations.

9. **Build and component structure**
   - `CMakeLists.txt`, `main/CMakeLists.txt`, and `main/idf_component.yml` place the project inside the standard ESP-IDF component/build model.
   - The repo is built as an ESP-IDF firmware image, not a standalone host program.
   - `main/Kconfig.projbuild` exposes project-specific configuration options, including Wi-Fi SSID/password from the README.

10. **Development environment and reproducibility**
   - `flake.nix` and `flake.lock` define a reproducible Nix-based dev shell around ESP-IDF tooling.
   - The README’s `espbuild` workflow implies a build wrapper that prepares web assets and then runs the ESP-IDF build.
   - This affects developer workflow, but not the device runtime architecture.

11. **What the diagram should show**
   - A single ESP32 device exposing an HTTP server over Wi-Fi.
   - Three main request paths: static pages/assets, sysinfo generation, and guestbook read/write.
   - Durable guestbook storage on littlefs in flash.
   - A build-time asset pipeline that transforms `main/pages` and `main/assets` into generated static content before firmware compilation.

Main entry points: [`main/server.c`](https://github.com/psynyde/esp32-win98-server/blob/master/main/server.c) (HTTP server), [`main/CMakeLists.txt`](https://github.com/psynyde/esp32-win98-server/blob/master/main/CMakeLists.txt) (App build), [`main/Kconfig.projbuild`](https://github.com/psynyde/esp32-win98-server/blob/master/main/Kconfig.projbuild) (Project config), [`main/main.c`](https://github.com/psynyde/esp32-win98-server/blob/master/main/main.c) (App entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Firmware runtime"]
  node_app_entry["App entry<br/>ESP-IDF main<br/>[main.c]"]
  node_server["HTTP server<br/>request router<br/>[server.c]"]
  node_core["Core services<br/>shared helpers<br/>[core.c]"]
  node_sysinfo["Sysinfo view<br/>dynamic endpoint"]
  node_guestbook["Guestbook<br/>stateful endpoint"]
  node_storage[("LittleFS<br/>flash storage")]
end

subgraph group_content["Web content"]
  node_pages["HTML pages<br/>static content"]
  node_assets["Shared assets<br/>static assets"]
end

subgraph group_build["Build and config"]
  node_flash_map["Flash map<br/>partition table<br/>[partitions.csv]"]
  node_build_assets["Asset build<br/>content pipeline"]
  node_root_cmake["Root build<br/>ESP-IDF build<br/>[CMakeLists.txt]"]
  node_main_cmake["App build<br/>component build<br/>[CMakeLists.txt]"]
  node_component_yml["Component manifest<br/>idf metadata<br/>[idf_component.yml]"]
  node_kconfig["Project config<br/>Kconfig<br/>[Kconfig.projbuild]"]
  node_sdkconfig["Default config<br/>sdkconfig<br/>[sdkconfig.default]"]
  node_nix["Dev shell<br/>Nix flake<br/>[flake.nix]"]
  node_readme["README<br/>project guide<br/>[README.md]"]
end

node_app_entry -->|"initializes"| node_core
node_app_entry -->|"starts"| node_server
node_server -->|"serves"| node_pages
node_server -->|"serves"| node_assets
node_server -->|"routes"| node_sysinfo
node_server -->|"routes"| node_guestbook
node_sysinfo -->|"uses"| node_core
node_sysinfo -->|"responds via"| node_server
node_guestbook -->|"persists to"| node_storage
node_guestbook -->|"responds via"| node_server
node_storage -->|"depends on"| node_flash_map
node_build_assets -->|"processes"| node_pages
node_build_assets -->|"processes"| node_assets
node_build_assets -->|"feeds"| node_server
node_root_cmake -->|"includes"| node_main_cmake
node_main_cmake -->|"uses"| node_component_yml
node_main_cmake -->|"exposes"| node_kconfig
node_sdkconfig -->|"seeds"| node_kconfig
node_nix -->|"supports"| node_root_cmake
node_readme -->|"documents"| node_build_assets
node_readme -->|"documents"| node_kconfig

click node_app_entry "https://github.com/psynyde/esp32-win98-server/blob/master/main/main.c"
click node_server "https://github.com/psynyde/esp32-win98-server/blob/master/main/server.c"
click node_core "https://github.com/psynyde/esp32-win98-server/blob/master/main/core.c"
click node_flash_map "https://github.com/psynyde/esp32-win98-server/blob/master/partitions.csv"
click node_pages "https://github.com/psynyde/esp32-win98-server/tree/master/main/pages"
click node_assets "https://github.com/psynyde/esp32-win98-server/tree/master/main/assets"
click node_root_cmake "https://github.com/psynyde/esp32-win98-server/blob/master/CMakeLists.txt"
click node_main_cmake "https://github.com/psynyde/esp32-win98-server/blob/master/main/CMakeLists.txt"
click node_component_yml "https://github.com/psynyde/esp32-win98-server/blob/master/main/idf_component.yml"
click node_kconfig "https://github.com/psynyde/esp32-win98-server/blob/master/main/Kconfig.projbuild"
click node_sdkconfig "https://github.com/psynyde/esp32-win98-server/blob/master/sdkconfig.default"
click node_nix "https://github.com/psynyde/esp32-win98-server/blob/master/flake.nix"
click node_readme "https://github.com/psynyde/esp32-win98-server/blob/master/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_entry,node_server,node_core,node_sysinfo,node_guestbook,node_storage toneBlue
class node_pages,node_assets toneAmber
class node_flash_map,node_build_assets,node_root_cmake,node_main_cmake,node_component_yml,node_kconfig,node_sdkconfig,node_nix,node_readme toneMint
```

## Components

### Firmware runtime

ESP32 app lifecycle and request handling on device

- [App entry](https://github.com/psynyde/esp32-win98-server/blob/master/main/main.c): ESP-IDF main · Firmware entrypoint that starts the device application · `main/main.c`
- [HTTP server](https://github.com/psynyde/esp32-win98-server/blob/master/main/server.c): request router · Serves browser requests and dispatches site routes · `main/server.c`
- [Core services](https://github.com/psynyde/esp32-win98-server/blob/master/main/core.c): shared helpers · Common application logic used by startup and handlers · `main/core.c`
- **Sysinfo view**: dynamic endpoint · Reads ESP32 runtime/device state and renders it in the site
- **Guestbook**: stateful endpoint · Handles guestbook reads and writes through the web server
- **LittleFS**: flash storage · Persistent flash-backed storage for guestbook entries

### Web content

Prebuilt pages and shared assets served by the firmware

- [HTML pages](https://github.com/psynyde/esp32-win98-server/tree/master/main/pages): static content · Prebuilt site pages served by the firmware · `main/pages`
- [Shared assets](https://github.com/psynyde/esp32-win98-server/tree/master/main/assets): static assets · Styles, images, and scripts bundled into the site · `main/assets`

### Build and config

ESP-IDF, partitioning, and developer workflow

- [Flash map](https://github.com/psynyde/esp32-win98-server/blob/master/partitions.csv): partition table · Defines firmware and storage layout on ESP32 flash · `partitions.csv`
- **Asset build**: content pipeline · Transforms source pages and assets into firmware-ready static content
- [Root build](https://github.com/psynyde/esp32-win98-server/blob/master/CMakeLists.txt): ESP-IDF build · Top-level firmware build entry for the repository · `CMakeLists.txt`
- [App build](https://github.com/psynyde/esp32-win98-server/blob/master/main/CMakeLists.txt): component build · Build rules for the ESP32 application component · `main/CMakeLists.txt`
- [Component manifest](https://github.com/psynyde/esp32-win98-server/blob/master/main/idf_component.yml): idf metadata · Declares component dependencies for the app · `main/idf_component.yml`
- [Project config](https://github.com/psynyde/esp32-win98-server/blob/master/main/Kconfig.projbuild): Kconfig · Project-specific configuration options exposed to menuconfig · `main/Kconfig.projbuild`
- [Default config](https://github.com/psynyde/esp32-win98-server/blob/master/sdkconfig.default): sdkconfig · Baseline ESP-IDF firmware settings · `sdkconfig.default`
- [Dev shell](https://github.com/psynyde/esp32-win98-server/blob/master/flake.nix): Nix flake · Reproducible development environment for ESP-IDF tooling · `flake.nix`
- [README](https://github.com/psynyde/esp32-win98-server/blob/master/README.md): project guide · Documents the site, setup flow, and build workflow · `README.md`

## Connections

- App entry → Core services: initializes · Startup uses shared helpers during firmware initialization
- App entry → HTTP server: starts · Entrypoint hands off to the HTTP serving subsystem
- HTTP server → HTML pages: serves · Routes browser requests to static HTML pages
- HTTP server → Shared assets: serves · Delivers shared static resources to the browser
- HTTP server → Sysinfo view: routes · Dispatches sysinfo requests to dynamic device-state rendering
- HTTP server → Guestbook: routes · Dispatches guestbook requests to read/write handlers
- Sysinfo view → Core services: uses · Dynamic page logic relies on common application services
- Sysinfo view → HTTP server: responds via · Sysinfo content is emitted through the web server boundary
- Guestbook → LittleFS: persists to · Guestbook entries are written to flash-backed LittleFS
- Guestbook → HTTP server: responds via · Form submissions and reads flow through HTTP handlers
- LittleFS → Flash map: depends on · Filesystem persistence requires a dedicated flash partition
- Asset build → HTML pages: processes · Build step consumes authored HTML pages
- Asset build → Shared assets: processes · Build step consumes shared static resources
- Asset build → HTTP server: feeds · Generated static content is packaged for serving at runtime
- Root build → App build: includes · Top-level build delegates to the application component
- App build → Component manifest: uses · Component build is shaped by declared dependencies
- App build → Project config: exposes · Component build surfaces project configuration options
- Default config → Project config: seeds · Default settings provide baseline values for configurable options
- Dev shell → Root build: supports · Reproducible dev environment wraps the ESP-IDF build
- README → Asset build: documents · Project guide describes the asset preparation and build workflow
- README → Project config: documents · Project guide explains runtime configuration such as Wi-Fi setup
