# cptkirki/printsphere architecture

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

- Interactive diagram: https://gitdiagram.com/cptkirki/printsphere
- Repository: https://github.com/cptkirki/printsphere

## Overview

PrintSphere is ESP32-S3 firmware for a Bambu printer companion display. At boot, the application loads persisted settings, brings up Wi-Fi and setup access, starts cloud/local printer and camera clients, then updates the on-device UI with printer, power, and notification state. The product also exposes Web Config for provisioning, profiles, display options, and OTA updates. Cloud and LAN are distinct status/control sources; hybrid selection is part of the documented workflow. Unsampled portal, UI, and resolver internals are represented at their implementation paths; edges are limited to visible calls or documented relationships.

Main entry points: [`main/src/application.cpp`](https://github.com/cptkirki/printsphere/blob/main/main/src/application.cpp) (Application Loop), [`main/src/bambu_cloud_client.cpp`](https://github.com/cptkirki/printsphere/blob/main/main/src/bambu_cloud_client.cpp) (Bambu Cloud Client), [`main/src/printer_client.cpp`](https://github.com/cptkirki/printsphere/blob/main/main/src/printer_client.cpp) (Local Printer Client), [`main/src/setup_portal.cpp`](https://github.com/cptkirki/printsphere/blob/main/main/src/setup_portal.cpp) (Web Config Portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_appmain["Firmware Entry<br/>[app_main.cpp]"]
  node_application["Application Loop<br/>[application.cpp]"]
  node_config[("Config Store<br/>[config_store.cpp]")]
  node_portal["Web Config Portal<br/>[setup_portal.cpp]"]
  node_provision["USB Provisioning"]
end

subgraph group_connectivity["Network and Printer"]
  node_wifi["Wi-Fi Manager<br/>[wifi_manager.cpp]"]
  node_cloud["Bambu Cloud Client"]
  node_local["Local Printer Client<br/>[printer_client.cpp]"]
  node_resolver["Status Resolver"]
  node_state["Printer State<br/>[printer_state.cpp]"]
  node_camera["Camera Snapshots"]
  node_bambustatus["Status Mapping<br/>[bambu_status.cpp]"]
  node_errors["Error Lookup<br/>[error_lookup.cpp]"]
  node_telemetry["MQTT Telemetry<br/>[mqtt_telemetry.hpp]"]
end

subgraph group_presentation["Display and Interaction"]
  node_ui["Display UI<br/>[ui.cpp]"]
  node_audio["Sound Notifications<br/>[audio_notifier.cpp]"]
end

subgraph group_device["Device Services"]
  node_pmu["Power Management<br/>[pmu.cpp]"]
  node_timesync["Time and Timezone<br/>[time_sync.cpp]"]
end

subgraph group_hardware["Board Hardware"]
  node_amoled["AMOLED Board Support"]
  node_lcd["LCD Board Support"]
  node_xpowers["Power Chip Definitions<br/>[XPowersParams.hpp]"]
end

node_user(("Device User"))
node_printer(("Bambu Printer"))
node_cloudservice(("Bambu Cloud"))

node_user -->|"configures"| node_portal
node_appmain -->|"starts"| node_application
node_application -->|"initializes and loads"| node_config
node_application -->|"initializes"| node_wifi
node_application -->|"starts"| node_portal
node_application -->|"starts"| node_provision
node_application -->|"initializes"| node_pmu
node_application -->|"initializes"| node_ui
node_application -->|"initializes"| node_audio
node_application -->|"sets timezone"| node_timesync
node_application -->|"configures and starts"| node_cloud
node_application -->|"configures and starts"| node_local
node_application -->|"configures and starts"| node_camera
node_portal -->|"manages settings"| node_config
node_cloud -->|"connects to"| node_cloudservice
node_cloud -->|"receives status and sends commands"| node_printer
node_local -->|"receives status and sends commands"| node_printer
node_camera -->|"fetches snapshots"| node_printer
node_application -.->|"selects status source"| node_resolver
node_resolver -.->|"resolves printer state"| node_state
node_cloud -.->|"updates status"| node_state
node_local -.->|"updates status"| node_state
node_application -->|"uses board support"| node_amoled
node_application -->|"uses board support"| node_lcd
node_amoled -.->|"power integration"| node_xpowers

click node_appmain "https://github.com/cptkirki/printsphere/blob/main/main/app_main.cpp"
click node_application "https://github.com/cptkirki/printsphere/blob/main/main/src/application.cpp"
click node_config "https://github.com/cptkirki/printsphere/blob/main/main/src/config_store.cpp"
click node_portal "https://github.com/cptkirki/printsphere/blob/main/main/src/setup_portal.cpp"
click node_provision "https://github.com/cptkirki/printsphere/blob/main/main/src/serial_provisioner.cpp"
click node_wifi "https://github.com/cptkirki/printsphere/blob/main/main/src/wifi_manager.cpp"
click node_cloud "https://github.com/cptkirki/printsphere/blob/main/main/src/bambu_cloud_client.cpp"
click node_local "https://github.com/cptkirki/printsphere/blob/main/main/src/printer_client.cpp"
click node_resolver "https://github.com/cptkirki/printsphere/blob/main/main/src/status_resolver.cpp"
click node_state "https://github.com/cptkirki/printsphere/blob/main/main/src/printer_state.cpp"
click node_camera "https://github.com/cptkirki/printsphere/blob/main/main/src/p1s_camera_client.cpp"
click node_bambustatus "https://github.com/cptkirki/printsphere/blob/main/main/src/bambu_status.cpp"
click node_errors "https://github.com/cptkirki/printsphere/blob/main/main/src/error_lookup.cpp"
click node_ui "https://github.com/cptkirki/printsphere/blob/main/main/src/ui.cpp"
click node_audio "https://github.com/cptkirki/printsphere/blob/main/main/src/audio_notifier.cpp"
click node_pmu "https://github.com/cptkirki/printsphere/blob/main/main/src/pmu.cpp"
click node_timesync "https://github.com/cptkirki/printsphere/blob/main/main/src/time_sync.cpp"
click node_telemetry "https://github.com/cptkirki/printsphere/blob/main/main/include/printsphere/mqtt_telemetry.hpp"
click node_amoled "https://github.com/cptkirki/printsphere/blob/main/components/esp32_s3_touch_amoled_1_75/esp32_s3_touch_amoled_1_75.c"
click node_lcd "https://github.com/cptkirki/printsphere/blob/main/components/esp32_s3_touch_lcd_2_8c/esp32_s3_touch_lcd_2_8c.c"
click node_xpowers "https://github.com/cptkirki/printsphere/blob/main/components/XPowersLib/src/XPowersParams.hpp"

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_appmain,node_application,node_config,node_portal,node_provision,node_user toneBlue
class node_wifi,node_cloud,node_local,node_resolver,node_state,node_camera,node_bambustatus,node_errors,node_telemetry toneAmber
class node_ui,node_audio toneMint
class node_pmu,node_timesync toneRose
class node_amoled,node_lcd,node_xpowers,node_printer,node_cloudservice toneIndigo
```

## Components

### Application

- [Firmware Entry](https://github.com/cptkirki/printsphere/blob/main/main/app_main.cpp): `main/app_main.cpp`
- [Application Loop](https://github.com/cptkirki/printsphere/blob/main/main/src/application.cpp): `main/src/application.cpp`
- [Config Store](https://github.com/cptkirki/printsphere/blob/main/main/src/config_store.cpp): `main/src/config_store.cpp`
- [Web Config Portal](https://github.com/cptkirki/printsphere/blob/main/main/src/setup_portal.cpp): `main/src/setup_portal.cpp`
- [USB Provisioning](https://github.com/cptkirki/printsphere/blob/main/main/src/serial_provisioner.cpp): `main/src/serial_provisioner.cpp`

### Network and Printer

- [Wi-Fi Manager](https://github.com/cptkirki/printsphere/blob/main/main/src/wifi_manager.cpp): `main/src/wifi_manager.cpp`
- [Bambu Cloud Client](https://github.com/cptkirki/printsphere/blob/main/main/src/bambu_cloud_client.cpp): `main/src/bambu_cloud_client.cpp`
- [Local Printer Client](https://github.com/cptkirki/printsphere/blob/main/main/src/printer_client.cpp): `main/src/printer_client.cpp`
- [Status Resolver](https://github.com/cptkirki/printsphere/blob/main/main/src/status_resolver.cpp): `main/src/status_resolver.cpp`
- [Printer State](https://github.com/cptkirki/printsphere/blob/main/main/src/printer_state.cpp): `main/src/printer_state.cpp`
- [Camera Snapshots](https://github.com/cptkirki/printsphere/blob/main/main/src/p1s_camera_client.cpp): `main/src/p1s_camera_client.cpp`
- [Status Mapping](https://github.com/cptkirki/printsphere/blob/main/main/src/bambu_status.cpp): `main/src/bambu_status.cpp`
- [Error Lookup](https://github.com/cptkirki/printsphere/blob/main/main/src/error_lookup.cpp): `main/src/error_lookup.cpp`
- [MQTT Telemetry](https://github.com/cptkirki/printsphere/blob/main/main/include/printsphere/mqtt_telemetry.hpp): `main/include/printsphere/mqtt_telemetry.hpp`

### Display and Interaction

- [Display UI](https://github.com/cptkirki/printsphere/blob/main/main/src/ui.cpp): `main/src/ui.cpp`
- [Sound Notifications](https://github.com/cptkirki/printsphere/blob/main/main/src/audio_notifier.cpp): `main/src/audio_notifier.cpp`

### Device Services

- [Power Management](https://github.com/cptkirki/printsphere/blob/main/main/src/pmu.cpp): `main/src/pmu.cpp`
- [Time and Timezone](https://github.com/cptkirki/printsphere/blob/main/main/src/time_sync.cpp): `main/src/time_sync.cpp`

### Board Hardware

- [AMOLED Board Support](https://github.com/cptkirki/printsphere/blob/main/components/esp32_s3_touch_amoled_1_75/esp32_s3_touch_amoled_1_75.c): `components/esp32_s3_touch_amoled_1_75/esp32_s3_touch_amoled_1_75.c`
- [LCD Board Support](https://github.com/cptkirki/printsphere/blob/main/components/esp32_s3_touch_lcd_2_8c/esp32_s3_touch_lcd_2_8c.c): `components/esp32_s3_touch_lcd_2_8c/esp32_s3_touch_lcd_2_8c.c`
- [Power Chip Definitions](https://github.com/cptkirki/printsphere/blob/main/components/XPowersLib/src/XPowersParams.hpp): `components/XPowersLib/src/XPowersParams.hpp`

### Other components

- **Device User**
- **Bambu Printer**
- **Bambu Cloud**

## Connections

- Device User → Web Config Portal: configures (evidence: `README.md`)
- Firmware Entry → Application Loop: starts (evidence: `main/app_main.cpp`)
- Application Loop → Config Store: initializes and loads (evidence: `main/src/application.cpp`)
- Application Loop → Wi-Fi Manager: initializes (evidence: `main/src/application.cpp`)
- Application Loop → Web Config Portal: starts (evidence: `main/src/application.cpp`)
- Application Loop → USB Provisioning: starts (evidence: `main/src/application.cpp`)
- Application Loop → Power Management: initializes (evidence: `main/src/application.cpp`)
- Application Loop → Display UI: initializes (evidence: `main/src/application.cpp`)
- Application Loop → Sound Notifications: initializes (evidence: `main/src/application.cpp`)
- Application Loop → Time and Timezone: sets timezone (evidence: `main/src/application.cpp`)
- Application Loop → Bambu Cloud Client: configures and starts (evidence: `main/src/application.cpp`)
- Application Loop → Local Printer Client: configures and starts (evidence: `main/src/application.cpp`)
- Application Loop → Camera Snapshots: configures and starts (evidence: `main/src/application.cpp`)
- Web Config Portal → Config Store: manages settings
- Bambu Cloud Client → Bambu Cloud: connects to (evidence: `README.md`)
- Bambu Cloud Client → Bambu Printer: receives status and sends commands (evidence: `README.md`)
- Local Printer Client → Bambu Printer: receives status and sends commands (evidence: `README.md`)
- Camera Snapshots → Bambu Printer: fetches snapshots (evidence: `README.md`)
- Application Loop → Status Resolver: selects status source
- Status Resolver → Printer State: resolves printer state
- Bambu Cloud Client → Printer State: updates status
- Local Printer Client → Printer State: updates status
- Application Loop → AMOLED Board Support: uses board support (evidence: `main/src/application.cpp`)
- Application Loop → LCD Board Support: uses board support (evidence: `main/src/application.cpp`)
- AMOLED Board Support → Power Chip Definitions: power integration