# jef-sure/dotview-clock architecture

> Architecture diagram of the GitHub repository jef-sure/dotview-clock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jef-sure/dotview-clock
- Repository: https://github.com/jef-sure/dotview-clock

## Overview

This ESP32 firmware runs a dot-font clock: users provision Wi-Fi and location, then the device obtains time-zone and weather context and renders animated time and weather across paired OLED displays. The README documents setup, automatic or manual location, forecasts, color transitions, and the display library’s virtual-screen and font capabilities. Source excerpts are partial, so links between orchestration and unsampled subsystems are based on documented behavior; uncertain implementation details are omitted.

Main entry points: [`main/main.c`](https://github.com/jef-sure/dotview-clock/blob/main/main/main.c) (Clock firmware), [`main/http_client_request.c`](https://github.com/jef-sure/dotview-clock/blob/main/main/http_client_request.c) (HTTP client), [`main/weather.c`](https://github.com/jef-sure/dotview-clock/blob/main/main/weather.c) (Weather processing), [`main/provisioning.c`](https://github.com/jef-sure/dotview-clock/blob/main/main/provisioning.c) (Wi-Fi provisioning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Provisioning"]
  node_firmware["Clock firmware<br/>[main.c]"]
  node_provision["Wi-Fi provisioning<br/>[provisioning.c]"]
  node_qrcode["QR generation"]
  node_web["Settings interface<br/>[http_server.c]"]
  node_config["Persistent settings<br/>[nvs_config.c]"]
end

subgraph group_context["Time and weather"]
  node_location["Location lookup<br/>[auto_location.c]"]
  node_tz["Time-zone setup<br/>[tzones.c]"]
  node_weather["Weather processing<br/>[weather.c]"]
  node_http["HTTP client"]
  node_json["JSON parsing<br/>[mjson.c]"]
end

subgraph group_render["Clock rendering"]
  node_draw["Clock and weather drawing<br/>[main.c]"]
  node_font["Font rendering and morphs<br/>[font.c]"]
  node_fontdata["Bundled fonts<br/>[CasusDotView.c]"]
end

subgraph group_display["Display component"]
  node_dgx["Drawing primitives<br/>[draw.c]"]
  node_vscreen["Virtual screens<br/>[vscreen.c]"]
  node_oled["SSD1351 driver<br/>[ssd1351.c]"]
  node_spi["ESP32 SPI bus<br/>[spi_esp32.c]"]
end

node_user(("Clock user"))
node_openweather(("OpenWeather"))
node_ipinfo(("ipinfo"))
node_internet(("Time servers"))
node_screens["Paired OLED displays"]

node_user -->|"sets up Wi-Fi"| node_provision
node_provision -->|"generates code"| node_qrcode
node_user -->|"enters settings"| node_web
node_web -->|"saves settings"| node_config
node_firmware -->|"starts setup"| node_provision
node_firmware -->|"enables settings"| node_web
node_firmware -->|"requests location"| node_location
node_location -->|"requests lookup"| node_http
node_http -.->|"sends request"| node_ipinfo
node_firmware -->|"sets time zone"| node_tz
node_firmware -->|"polls weather"| node_weather
node_weather -->|"requests forecast"| node_http
node_http -->|"sends request"| node_openweather
node_http -.->|"synchronizes time"| node_internet
node_weather -->|"parses response"| node_json
node_firmware -->|"dispatches display updates"| node_draw
node_draw -->|"draws glyphs"| node_font
node_font -->|"reads glyph data"| node_fontdata
node_draw -->|"draws graphics"| node_dgx
node_draw -->|"renders frames"| node_vscreen
node_vscreen -->|"transfers image"| node_oled
node_oled -->|"sends display data"| node_spi
node_spi -->|"drives displays"| node_screens

click node_firmware "https://github.com/jef-sure/dotview-clock/blob/main/main/main.c"
click node_provision "https://github.com/jef-sure/dotview-clock/blob/main/main/provisioning.c"
click node_qrcode "https://github.com/jef-sure/dotview-clock/tree/main/managed_components/espressif__qrcode"
click node_web "https://github.com/jef-sure/dotview-clock/blob/main/main/http_server.c"
click node_config "https://github.com/jef-sure/dotview-clock/blob/main/main/nvs_config.c"
click node_location "https://github.com/jef-sure/dotview-clock/blob/main/main/auto_location.c"
click node_tz "https://github.com/jef-sure/dotview-clock/blob/main/main/tzones.c"
click node_weather "https://github.com/jef-sure/dotview-clock/blob/main/main/weather.c"
click node_http "https://github.com/jef-sure/dotview-clock/blob/main/main/http_client_request.c"
click node_json "https://github.com/jef-sure/dotview-clock/blob/main/components/mjson/src/mjson.c"
click node_draw "https://github.com/jef-sure/dotview-clock/blob/main/main/main.c"
click node_font "https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/font.c"
click node_fontdata "https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/fonts/CasusDotView.c"
click node_dgx "https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/draw.c"
click node_vscreen "https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/drivers/vscreen.c"
click node_oled "https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/drivers/ssd1351.c"
click node_spi "https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/bus/spi_esp32.c"

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_firmware,node_provision,node_qrcode,node_web,node_config,node_user toneBlue
class node_location,node_tz,node_weather,node_http,node_json toneAmber
class node_draw,node_font,node_fontdata,node_internet toneMint
class node_dgx,node_vscreen,node_oled,node_spi toneRose
class node_openweather,node_ipinfo,node_screens toneIndigo
```

## Components

### Provisioning

- [Clock firmware](https://github.com/jef-sure/dotview-clock/blob/main/main/main.c): `main/main.c`
- [Wi-Fi provisioning](https://github.com/jef-sure/dotview-clock/blob/main/main/provisioning.c): `main/provisioning.c`
- [QR generation](https://github.com/jef-sure/dotview-clock/tree/main/managed_components/espressif__qrcode): `managed_components/espressif__qrcode`
- [Settings interface](https://github.com/jef-sure/dotview-clock/blob/main/main/http_server.c): `main/http_server.c`
- [Persistent settings](https://github.com/jef-sure/dotview-clock/blob/main/main/nvs_config.c): `main/nvs_config.c`

### Time and weather

- [Location lookup](https://github.com/jef-sure/dotview-clock/blob/main/main/auto_location.c): `main/auto_location.c`
- [Time-zone setup](https://github.com/jef-sure/dotview-clock/blob/main/main/tzones.c): `main/tzones.c`
- [Weather processing](https://github.com/jef-sure/dotview-clock/blob/main/main/weather.c): `main/weather.c`
- [HTTP client](https://github.com/jef-sure/dotview-clock/blob/main/main/http_client_request.c): `main/http_client_request.c`
- [JSON parsing](https://github.com/jef-sure/dotview-clock/blob/main/components/mjson/src/mjson.c): `components/mjson/src/mjson.c`

### Clock rendering

- [Clock and weather drawing](https://github.com/jef-sure/dotview-clock/blob/main/main/main.c): `main/main.c`
- [Font rendering and morphs](https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/font.c): `components/dgx/src/font.c`
- [Bundled fonts](https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/fonts/CasusDotView.c): `components/dgx/src/fonts/CasusDotView.c`

### Display component

- [Drawing primitives](https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/draw.c): `components/dgx/src/draw.c`
- [Virtual screens](https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/drivers/vscreen.c): `components/dgx/src/drivers/vscreen.c`
- [SSD1351 driver](https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/drivers/ssd1351.c): `components/dgx/src/drivers/ssd1351.c`
- [ESP32 SPI bus](https://github.com/jef-sure/dotview-clock/blob/main/components/dgx/src/bus/spi_esp32.c): `components/dgx/src/bus/spi_esp32.c`

### Other components

- **Clock user**
- **OpenWeather**
- **ipinfo**
- **Time servers**
- **Paired OLED displays**

## Connections

- Clock user → Wi-Fi provisioning: sets up Wi-Fi
- Wi-Fi provisioning → QR generation: generates code
- Clock user → Settings interface: enters settings
- Settings interface → Persistent settings: saves settings
- Clock firmware → Wi-Fi provisioning: starts setup
- Clock firmware → Settings interface: enables settings
- Clock firmware → Location lookup: requests location
- Location lookup → HTTP client: requests lookup
- HTTP client → ipinfo: sends request
- Clock firmware → Time-zone setup: sets time zone
- Clock firmware → Weather processing: polls weather
- Weather processing → HTTP client: requests forecast
- HTTP client → OpenWeather: sends request
- HTTP client → Time servers: synchronizes time
- Weather processing → JSON parsing: parses response
- Clock firmware → Clock and weather drawing: dispatches display updates
- Clock and weather drawing → Font rendering and morphs: draws glyphs
- Font rendering and morphs → Bundled fonts: reads glyph data
- Clock and weather drawing → Drawing primitives: draws graphics
- Clock and weather drawing → Virtual screens: renders frames
- Virtual screens → SSD1351 driver: transfers image
- SSD1351 driver → ESP32 SPI bus: sends display data
- ESP32 SPI bus → Paired OLED displays: drives displays