# cfosteriv/promist architecture

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

- Interactive diagram: https://gitdiagram.com/cfosteriv/promist
- Repository: https://github.com/cfosteriv/promist

## Overview

ProMist is an ESP32 retrofit controller with an iPhone app, authenticated BLE, and Matter/Apple Home control, while retaining local panel and RF operation. The main workflow is a user action in the app or Home being delivered over BLE or Matter to firmware’s shared DeviceController, then applied to appliance hardware; firmware state is published back to the control surfaces. The README documents this architecture, and the source index confirms key module references. Several firmware and UI subsystems are represented by their exact enclosing paths because their implementation files were not sampled.

Main entry points: [`ProMistIDF/main/DeviceController.cpp`](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/DeviceController.cpp) (Shared device state), [`ProMist/ProMist/Services/ProMistBLECentral.swift`](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistBLECentral.swift) (BLE session owner), [`ProMistIDF/main/BleManager.cpp`](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/BleManager.cpp) (Firmware BLE service), [`ProMist/ProMist/Views/DeviceView.swift`](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Views/DeviceView.swift) (SwiftUI controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["iPhone app"]
  node_appui["SwiftUI controls<br/>[DeviceView.swift]"]
  node_deviceviews["Dashboard and setup"]
  node_deviceidentity[("Known fan state<br/>[KnownFan.swift]")]
  node_homemanager["Home association"]
  node_mattercommission["Matter commissioning"]
  node_appintents["App Intents"]
end

subgraph group_ble["BLE control"]
  node_blecentral["BLE session owner"]
  node_bleprotocol["BLE protocol"]
  node_bleauth["Owner authentication"]
  node_blecommands["Command transactions"]
  node_blediagnostics["Diagnostic retrieval"]
end

subgraph group_firmware["Device firmware"]
  node_blefirmware["Firmware BLE service<br/>[BleManager.cpp]"]
  node_controller["Shared device state"]
  node_firmwareentry["Firmware composition<br/>[main.cpp]"]
  node_profiles["Breeze profiles<br/>[BreezeProfiles.cpp]"]
  node_diagnostics[("Diagnostic log<br/>[DiagnosticLog.cpp]")]
end

subgraph group_hardware["Appliance hardware"]
  node_localcontrols["Panel and RF input<br/>[UserInterface.cpp]"]
  node_fanmotor["Fan and tach<br/>[FanMotor.cpp]"]
  node_oscillation["Oscillation control"]
  node_mist["Mister pump<br/>[MisterPump.cpp]"]
end

subgraph group_home["Matter and Home"]
  node_matterendpoint["Matter fan endpoint"]
end

node_iphone(("iPhone user"))
node_homeapp(("Apple Home / Siri"))

node_iphone -->|"operates"| node_appui
node_appui -->|"issues controls"| node_blecentral
node_appui -->|"opens settings"| node_deviceviews
node_blecentral -.->|"updates records"| node_deviceidentity
node_blecentral -->|"coordinates auth"| node_bleauth
node_blecentral -->|"coordinates requests"| node_blecommands
node_blecentral -->|"coordinates retrieval"| node_blediagnostics
node_blecommands -->|"builds packets"| node_bleprotocol
node_blecommands -->|"sends commands"| node_blefirmware
node_blediagnostics -->|"requests logs"| node_blefirmware
node_bleauth -->|"authenticates owner"| node_blefirmware
node_blefirmware -->|"applies commands"| node_controller
node_firmwareentry -->|"starts service"| node_blefirmware
node_firmwareentry -->|"configures controller"| node_controller
node_controller -->|"publishes state"| node_matterendpoint
node_homeapp -->|"controls fan"| node_matterendpoint
node_matterendpoint -->|"writes attributes"| node_controller
node_homemanager -.->|"coordinates setup"| node_mattercommission
node_controller -.->|"shares state"| node_localcontrols
node_controller -.->|"drives fan"| node_fanmotor
node_controller -.->|"positions mechanism"| node_oscillation
node_controller -.->|"controls pump"| node_mist
node_controller -.->|"uses profiles"| node_profiles
node_controller -.->|"records events"| node_diagnostics
node_iphone -->|"invokes shortcuts"| node_appintents

click node_appui "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Views/DeviceView.swift"
click node_deviceviews "https://github.com/cfosteriv/promist/tree/main/ProMist/ProMist/Views"
click node_deviceidentity "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Models/KnownFan.swift"
click node_blecentral "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistBLECentral.swift"
click node_bleprotocol "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Models/ProMistBLEProtocol.swift"
click node_bleauth "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistBLEAuthenticationEngine.swift"
click node_blecommands "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistBLECommandEngine.swift"
click node_blediagnostics "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistDiagnosticsEngine.swift"
click node_blefirmware "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/BleManager.cpp"
click node_controller "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/DeviceController.cpp"
click node_firmwareentry "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/main.cpp"
click node_matterendpoint "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/EspMatterFanEndpoint.cpp"
click node_homemanager "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistHomeManager.swift"
click node_mattercommission "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistMatterCommissioningCoordinator.swift"
click node_localcontrols "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/UserInterface.cpp"
click node_fanmotor "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/FanMotor.cpp"
click node_oscillation "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/OscillationController.cpp"
click node_mist "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/MisterPump.cpp"
click node_profiles "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/BreezeProfiles.cpp"
click node_diagnostics "https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/DiagnosticLog.cpp"
click node_appintents "https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistAppIntents.swift"

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_appui,node_deviceviews,node_deviceidentity,node_homemanager,node_mattercommission,node_appintents,node_iphone toneBlue
class node_blecentral,node_bleprotocol,node_bleauth,node_blecommands,node_blediagnostics toneAmber
class node_blefirmware,node_controller,node_firmwareentry,node_profiles,node_diagnostics toneMint
class node_localcontrols,node_fanmotor,node_oscillation,node_mist toneRose
class node_matterendpoint,node_homeapp toneIndigo
```

## Components

### iPhone app

- [SwiftUI controls](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Views/DeviceView.swift): `ProMist/ProMist/Views/DeviceView.swift`
- [Dashboard and setup](https://github.com/cfosteriv/promist/tree/main/ProMist/ProMist/Views): `ProMist/ProMist/Views`
- [Known fan state](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Models/KnownFan.swift): `ProMist/ProMist/Models/KnownFan.swift`
- [Home association](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistHomeManager.swift): `ProMist/ProMist/Services/ProMistHomeManager.swift`
- [Matter commissioning](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistMatterCommissioningCoordinator.swift): `ProMist/ProMist/Services/ProMistMatterCommissioningCoordinator.swift`
- [App Intents](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistAppIntents.swift): `ProMist/ProMist/Services/ProMistAppIntents.swift`

### BLE control

- [BLE session owner](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistBLECentral.swift): `ProMist/ProMist/Services/ProMistBLECentral.swift`
- [BLE protocol](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Models/ProMistBLEProtocol.swift): `ProMist/ProMist/Models/ProMistBLEProtocol.swift`
- [Owner authentication](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistBLEAuthenticationEngine.swift): `ProMist/ProMist/Services/ProMistBLEAuthenticationEngine.swift`
- [Command transactions](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistBLECommandEngine.swift): `ProMist/ProMist/Services/ProMistBLECommandEngine.swift`
- [Diagnostic retrieval](https://github.com/cfosteriv/promist/blob/main/ProMist/ProMist/Services/ProMistDiagnosticsEngine.swift): `ProMist/ProMist/Services/ProMistDiagnosticsEngine.swift`

### Device firmware

- [Firmware BLE service](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/BleManager.cpp): `ProMistIDF/main/BleManager.cpp`
- [Shared device state](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/DeviceController.cpp): `ProMistIDF/main/DeviceController.cpp`
- [Firmware composition](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/main.cpp): `ProMistIDF/main/main.cpp`
- [Breeze profiles](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/BreezeProfiles.cpp): `ProMistIDF/main/BreezeProfiles.cpp`
- [Diagnostic log](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/DiagnosticLog.cpp): `ProMistIDF/main/DiagnosticLog.cpp`

### Appliance hardware

- [Panel and RF input](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/UserInterface.cpp): `ProMistIDF/main/UserInterface.cpp`
- [Fan and tach](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/FanMotor.cpp): `ProMistIDF/main/FanMotor.cpp`
- [Oscillation control](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/OscillationController.cpp): `ProMistIDF/main/OscillationController.cpp`
- [Mister pump](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/MisterPump.cpp): `ProMistIDF/main/MisterPump.cpp`

### Matter and Home

- [Matter fan endpoint](https://github.com/cfosteriv/promist/blob/main/ProMistIDF/main/EspMatterFanEndpoint.cpp): `ProMistIDF/main/EspMatterFanEndpoint.cpp`

### Other components

- **iPhone user**
- **Apple Home / Siri**

## Connections

- iPhone user → SwiftUI controls: operates (evidence: `README.md`)
- SwiftUI controls → BLE session owner: issues controls (evidence: `ProMist/ProMist/Views/DeviceView.swift`)
- SwiftUI controls → Dashboard and setup: opens settings (evidence: `ProMist/ProMist/Views/DeviceView.swift`)
- BLE session owner → Known fan state: updates records
- BLE session owner → Owner authentication: coordinates auth (evidence: `ProMist/ProMist/Services/ProMistBLECentral.swift`)
- BLE session owner → Command transactions: coordinates requests (evidence: `ProMist/ProMist/Services/ProMistBLECentral.swift`)
- BLE session owner → Diagnostic retrieval: coordinates retrieval (evidence: `ProMist/ProMist/Services/ProMistBLECentral.swift`)
- Command transactions → BLE protocol: builds packets (evidence: `ProMist/ProMist/Services/ProMistBLECommandEngine.swift`)
- Command transactions → Firmware BLE service: sends commands (evidence: `README.md`)
- Diagnostic retrieval → Firmware BLE service: requests logs (evidence: `README.md`)
- Owner authentication → Firmware BLE service: authenticates owner (evidence: `README.md`)
- Firmware BLE service → Shared device state: applies commands (evidence: `README.md`)
- Firmware composition → Firmware BLE service: starts service (evidence: `ProMistIDF/main/main.cpp`)
- Firmware composition → Shared device state: configures controller (evidence: `ProMistIDF/main/main.cpp`)
- Shared device state → Matter fan endpoint: publishes state (evidence: `README.md`)
- Apple Home / Siri → Matter fan endpoint: controls fan (evidence: `README.md`)
- Matter fan endpoint → Shared device state: writes attributes (evidence: `README.md`)
- Home association → Matter commissioning: coordinates setup
- Shared device state → Panel and RF input: shares state
- Shared device state → Fan and tach: drives fan
- Shared device state → Oscillation control: positions mechanism
- Shared device state → Mister pump: controls pump
- Shared device state → Breeze profiles: uses profiles
- Shared device state → Diagnostic log: records events
- iPhone user → App Intents: invokes shortcuts (evidence: `README.md`)
