# johnbaumb/klipperfleet architecture

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

- Interactive diagram: https://gitdiagram.com/johnbaumb/klipperfleet
- Repository: https://github.com/johnbaumb/klipperfleet

## Overview

KlipperFleet is a Mainsail-integrated web app for configuring, building, and flashing firmware across a printer’s MCU fleet. Users edit and save firmware profiles, register and assign devices, then run individual or batch build/flash actions; batch flashing checks device state, sequences downstream nodes before bridges, and streams progress to the UI. The backend also manages fleet/profile backups, device discovery and status, and service coordination. The graph reflects README-documented capabilities where source excerpts were unavailable; unsampled subsystem links are limited to the API entry point and supported product behavior.

Main entry points: [`backend/main.py`](https://github.com/johnbaumb/klipperfleet/blob/main/backend/main.py) (HTTP API and workflows), [`backend/flash_manager.py`](https://github.com/johnbaumb/klipperfleet/blob/main/backend/flash_manager.py) (Discovery and flasher), [`backend/build_manager.py`](https://github.com/johnbaumb/klipperfleet/blob/main/backend/build_manager.py) (Firmware builder), [`backend/fleet_manager.py`](https://github.com/johnbaumb/klipperfleet/blob/main/backend/fleet_manager.py) (Fleet registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_ui["Configurator and dashboard<br/>[index.html]"]
end

subgraph group_api["API orchestration"]
  node_api["HTTP API and workflows<br/>[main.py]"]
end

subgraph group_firmware["Firmware workflow"]
  node_kconfig["Kconfig profile engine<br/>[kconfig_manager.py]"]
  node_build["Firmware builder<br/>[build_manager.py]"]
  node_flash["Discovery and flasher<br/>[flash_manager.py]"]
  node_katapult["Katapult protocol"]
end

subgraph group_fleet["Fleet and state"]
  node_fleetmgr["Fleet registry<br/>[fleet_manager.py]"]
  node_fleetdata[("Fleet and profiles")]
  node_artifacts[("Build artifacts")]
end

subgraph group_integrations["Printer integrations"]
  node_moonraker["Moonraker"]
  node_klipper["Klipper or Kalico"]
  node_devices["Printer MCUs"]
  node_services["Printer services"]
end

node_operator(("Printer operator"))

node_operator -->|"uses"| node_ui
node_ui -->|"calls API"| node_api
node_api -->|"loads and saves"| node_kconfig
node_api -->|"builds profiles"| node_build
node_api -->|"discovers and flashes"| node_flash
node_api -->|"manages fleet"| node_fleetmgr
node_kconfig -->|"parses Kconfig"| node_klipper
node_build -->|"runs make"| node_klipper
node_build -->|"writes firmware"| node_artifacts
node_api -->|"imports and exports backups"| node_artifacts
node_fleetmgr -->|"reads and writes"| node_fleetdata
node_api -->|"queries status"| node_moonraker
node_flash -->|"queries printer state"| node_moonraker
node_flash -->|"discovers and flashes"| node_devices
node_flash -->|"uses protocol"| node_katapult
node_katapult -->|"sends bootloader commands"| node_devices
node_api -->|"stops and starts"| node_services
node_api -->|"updates flash versions"| node_fleetmgr

click node_ui "https://github.com/johnbaumb/klipperfleet/blob/main/ui/index.html"
click node_api "https://github.com/johnbaumb/klipperfleet/blob/main/backend/main.py"
click node_kconfig "https://github.com/johnbaumb/klipperfleet/blob/main/backend/kconfig_manager.py"
click node_build "https://github.com/johnbaumb/klipperfleet/blob/main/backend/build_manager.py"
click node_flash "https://github.com/johnbaumb/klipperfleet/blob/main/backend/flash_manager.py"
click node_katapult "https://github.com/johnbaumb/klipperfleet/blob/main/backend/katapult_protocol.py"
click node_fleetmgr "https://github.com/johnbaumb/klipperfleet/blob/main/backend/fleet_manager.py"

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_ui toneBlue
class node_api toneAmber
class node_kconfig,node_build,node_flash,node_katapult toneMint
class node_fleetmgr,node_fleetdata,node_artifacts toneRose
class node_moonraker,node_klipper,node_devices,node_services,node_operator toneIndigo
```

## Components

### Web interface

- [Configurator and dashboard](https://github.com/johnbaumb/klipperfleet/blob/main/ui/index.html): `ui/index.html`

### API orchestration

- [HTTP API and workflows](https://github.com/johnbaumb/klipperfleet/blob/main/backend/main.py): `backend/main.py`

### Firmware workflow

- [Kconfig profile engine](https://github.com/johnbaumb/klipperfleet/blob/main/backend/kconfig_manager.py): `backend/kconfig_manager.py`
- [Firmware builder](https://github.com/johnbaumb/klipperfleet/blob/main/backend/build_manager.py): `backend/build_manager.py`
- [Discovery and flasher](https://github.com/johnbaumb/klipperfleet/blob/main/backend/flash_manager.py): `backend/flash_manager.py`
- [Katapult protocol](https://github.com/johnbaumb/klipperfleet/blob/main/backend/katapult_protocol.py): `backend/katapult_protocol.py`

### Fleet and state

- [Fleet registry](https://github.com/johnbaumb/klipperfleet/blob/main/backend/fleet_manager.py): `backend/fleet_manager.py`
- **Fleet and profiles**
- **Build artifacts**

### Printer integrations

- **Moonraker**
- **Klipper or Kalico**
- **Printer MCUs**
- **Printer services**

### Other components

- **Printer operator**

## Connections

- Printer operator → Configurator and dashboard: uses
- Configurator and dashboard → HTTP API and workflows: calls API
- HTTP API and workflows → Kconfig profile engine: loads and saves
- HTTP API and workflows → Firmware builder: builds profiles
- HTTP API and workflows → Discovery and flasher: discovers and flashes
- HTTP API and workflows → Fleet registry: manages fleet
- Kconfig profile engine → Klipper or Kalico: parses Kconfig
- Firmware builder → Klipper or Kalico: runs make
- Firmware builder → Build artifacts: writes firmware
- HTTP API and workflows → Build artifacts: imports and exports backups
- Fleet registry → Fleet and profiles: reads and writes
- HTTP API and workflows → Moonraker: queries status
- Discovery and flasher → Moonraker: queries printer state
- Discovery and flasher → Printer MCUs: discovers and flashes
- Discovery and flasher → Katapult protocol: uses protocol
- Katapult protocol → Printer MCUs: sends bootloader commands
- HTTP API and workflows → Printer services: stops and starts
- HTTP API and workflows → Fleet registry: updates flash versions