# pangcrd/esp32-smart-photo-frame architecture

> Architecture diagram of the GitHub repository pangcrd/esp32-smart-photo-frame, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pangcrd/esp32-smart-photo-frame
- Repository: https://github.com/pangcrd/esp32-smart-photo-frame

## Overview

This is an ESP32 photo-frame firmware: people configure it through a browser dashboard or the device UI, while the frame reads JPEGs from SD storage and cycles them on its display. The web server also exposes WiFi setup, gallery management, weather, display settings, and system status; the README documents image editing, localization, themes, and reset actions. The map follows calls visible in sampled code and named interfaces; unsampled route and weather implementations are represented only where their paths are explicit, with uncertain wiring omitted.

Main entry points: [`Source code/src/web/web_server_manager.cpp`](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/web_server_manager.cpp) (HTTP API), [`Source code/src/main.cpp`](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/main.cpp) (Firmware entry), [`Source code/src/ui/ui_events.cpp`](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/ui_events.cpp) (UI interactions), [`Source code/src/jpg/jpg_gallery.cpp`](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/jpg/jpg_gallery.cpp) (JPEG slideshow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Firmware runtime"]
  node_boot["Firmware entry<br/>[main.cpp]"]
  node_monitor["System monitor<br/>[system_monitor.cpp]"]
  node_sd[("SD card storage<br/>[sd_card_conf.cpp]")]
  node_display["Display port<br/>[lvgl_port.cpp]"]
  node_battery["Battery sensing<br/>[bat_adc.cpp]"]
  node_littlefs[("Configuration store")]
end

subgraph group_presentation["Display experience"]
  node_gallery["JPEG slideshow<br/>[jpg_gallery.cpp]"]
  node_ui["LVGL interface<br/>[ui.c]"]
  node_events["UI interactions<br/>[ui_events.cpp]"]
  node_setup["Setup screens<br/>[ui_setup.c]"]
  node_galleryscreen["Gallery screen<br/>[ui_image_gallery.c]"]
end

subgraph group_management["Device management"]
  node_server["HTTP API"]
  node_webapp["Dashboard controls<br/>[app.js]"]
end

subgraph group_connectivity["Network services"]
  node_wifi["WiFi manager<br/>[wifi_manager.cpp]"]
  node_weather["Weather data<br/>[get_weather.cpp]"]
  node_time["Network time<br/>[get_ntp.cpp]"]
  node_api["Weather API<br/>[get_api_data.h]"]
end

node_user(("Frame user"))
node_browser["Browser dashboard<br/>[app.js]"]
node_internet(("Internet services"))

node_user -->|"manages frame"| node_browser
node_browser -->|"uses dashboard"| node_webapp
node_webapp -->|"HTTP requests"| node_server
node_boot -->|"updates"| node_monitor
node_boot -->|"starts and updates"| node_server
node_boot -->|"initializes"| node_display
node_boot -->|"initializes"| node_ui
node_boot -->|"updates"| node_events
node_boot -->|"ticks slideshow"| node_gallery
node_server -->|"reads status"| node_monitor
node_server -->|"manages WiFi"| node_wifi
node_server -->|"uploads and deletes"| node_sd
node_server -->|"persists settings"| node_littlefs
node_server -->|"serves weather"| node_weather
node_server -->|"serves time data"| node_time
node_wifi -->|"loads and saves"| node_littlefs
node_wifi -->|"connects"| node_internet
node_monitor -->|"checks card"| node_sd
node_gallery -->|"lists and reads JPEGs"| node_sd
node_gallery -->|"renders images"| node_display
node_events -->|"starts gallery"| node_gallery
node_events -->|"resets WiFi"| node_wifi
node_events -->|"reads weather"| node_weather
node_events -->|"reads charge"| node_battery
node_events -->|"updates widgets"| node_ui
node_ui -->|"shows setup"| node_setup
node_ui -->|"shows gallery"| node_galleryscreen
node_weather -->|"uses API data"| node_api
node_weather -.->|"fetches forecast"| node_internet
node_time -.->|"synchronizes"| node_internet

click node_browser "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/data/app.js"
click node_boot "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/main.cpp"
click node_server "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/web_server_manager.cpp"
click node_wifi "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/wifi/wifi_manager.cpp"
click node_webapp "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/data/app.js"
click node_monitor "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/sys/system_monitor.cpp"
click node_gallery "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/jpg/jpg_gallery.cpp"
click node_sd "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/drv/sd_card_conf.cpp"
click node_ui "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/ui.c"
click node_events "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/ui_events.cpp"
click node_setup "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/screens/ui_setup.c"
click node_galleryscreen "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/screens/ui_image_gallery.c"
click node_display "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/drv/lvgl_port.cpp"
click node_battery "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/drv/bat_adc.cpp"
click node_weather "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/get_weather.cpp"
click node_time "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/get_ntp.cpp"
click node_api "https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/get_api_data.h"

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_boot,node_monitor,node_sd,node_display,node_battery,node_littlefs,node_user,node_browser toneBlue
class node_gallery,node_ui,node_events,node_setup,node_galleryscreen toneAmber
class node_server,node_webapp toneMint
class node_wifi,node_weather,node_time,node_api toneRose
class node_internet toneIndigo
```

## Components

### Firmware runtime

- [Firmware entry](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/main.cpp): `Source code/src/main.cpp`
- [System monitor](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/sys/system_monitor.cpp): `Source code/src/sys/system_monitor.cpp`
- [SD card storage](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/drv/sd_card_conf.cpp): `Source code/src/drv/sd_card_conf.cpp`
- [Display port](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/drv/lvgl_port.cpp): `Source code/src/drv/lvgl_port.cpp`
- [Battery sensing](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/drv/bat_adc.cpp): `Source code/src/drv/bat_adc.cpp`
- **Configuration store**

### Display experience

- [JPEG slideshow](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/jpg/jpg_gallery.cpp): `Source code/src/jpg/jpg_gallery.cpp`
- [LVGL interface](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/ui.c): `Source code/src/ui/ui.c`
- [UI interactions](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/ui_events.cpp): `Source code/src/ui/ui_events.cpp`
- [Setup screens](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/screens/ui_setup.c): `Source code/src/ui/screens/ui_setup.c`
- [Gallery screen](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/ui/screens/ui_image_gallery.c): `Source code/src/ui/screens/ui_image_gallery.c`

### Device management

- [HTTP API](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/web_server_manager.cpp): `Source code/src/web/web_server_manager.cpp`
- [Dashboard controls](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/data/app.js): `Source code/data/app.js`

### Network services

- [WiFi manager](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/wifi/wifi_manager.cpp): `Source code/src/wifi/wifi_manager.cpp`
- [Weather data](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/get_weather.cpp): `Source code/src/web/get_weather.cpp`
- [Network time](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/get_ntp.cpp): `Source code/src/web/get_ntp.cpp`
- [Weather API](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/src/web/get_api_data.h): `Source code/src/web/get_api_data.h`

### Other components

- **Frame user**
- [Browser dashboard](https://github.com/pangcrd/esp32-smart-photo-frame/blob/main/Source%20code/data/app.js): `Source code/data/app.js`
- **Internet services**

## Connections

- Frame user → Browser dashboard: manages frame
- Browser dashboard → Dashboard controls: uses dashboard
- Dashboard controls → HTTP API: HTTP requests
- Firmware entry → System monitor: updates
- Firmware entry → HTTP API: starts and updates
- Firmware entry → Display port: initializes
- Firmware entry → LVGL interface: initializes
- Firmware entry → UI interactions: updates
- Firmware entry → JPEG slideshow: ticks slideshow
- HTTP API → System monitor: reads status
- HTTP API → WiFi manager: manages WiFi
- HTTP API → SD card storage: uploads and deletes
- HTTP API → Configuration store: persists settings
- HTTP API → Weather data: serves weather
- HTTP API → Network time: serves time data
- WiFi manager → Configuration store: loads and saves
- WiFi manager → Internet services: connects
- System monitor → SD card storage: checks card
- JPEG slideshow → SD card storage: lists and reads JPEGs
- JPEG slideshow → Display port: renders images
- UI interactions → JPEG slideshow: starts gallery
- UI interactions → WiFi manager: resets WiFi
- UI interactions → Weather data: reads weather
- UI interactions → Battery sensing: reads charge
- UI interactions → LVGL interface: updates widgets
- LVGL interface → Setup screens: shows setup
- LVGL interface → Gallery screen: shows gallery
- Weather data → Weather API: uses API data
- Weather data → Internet services: fetches forecast
- Network time → Internet services: synchronizes