# ilyakolos777/esp32-cam-security-system architecture

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

- Interactive diagram: https://gitdiagram.com/ilyakolos777/esp32-cam-security-system
- Repository: https://github.com/ilyakolos777/esp32-cam-security-system

## Overview

This is a desktop ESP32-CAM security-monitoring application. The principal workflow is to start a camera stream or motion detection from the UI, process incoming frames, and use MQTT commands to control camera-side actions; session activity is also presented as statistics and can be exported as a PDF. The graph includes the visible camera firmware and major UI/reporting modules. Some wiring is not shown in the excerpts, so uncertain firmware-to-broker links are omitted.

Main entry points: [`ui/main_window.py`](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/main_window.py) (Main window), [`main.py`](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/main.py) (Application launcher), [`core/camera.py`](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/core/camera.py) (MJPEG stream client), [`core/mqtt_client.py`](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/core/mqtt_client.py) (MQTT manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop application"]
  node_launcher["Application launcher<br/>[main.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_controls["Control panel<br/>[control_panel.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_vision["Video and detection"]
  node_camera_stream["MJPEG stream client<br/>[camera.py]"]
  node_motion["Motion detector<br/>[detector.py]"]
  node_video_view["Video display<br/>[video_display.py]"]
end

subgraph group_device["Camera device"]
  node_camera_service(("ESP32 camera stream"))
  node_camera_firmware["OV2640 driver<br/>[OV2640.cpp]"]
  node_firmware_app["Camera firmware app"]
  node_mqtt_manager["MQTT manager<br/>[mqtt_client.py]"]
end

subgraph group_session["Session reporting"]
  node_statistics["Session statistics<br/>[stats_tab.py]"]
  node_pdf_export["PDF report exporter<br/>[pdf_export.py]"]
end

node_operator(("Operator"))
node_mqtt_broker(("MQTT broker"))

node_operator -->|"starts app"| node_launcher
node_launcher -->|"reads settings"| node_settings
node_launcher -->|"creates window"| node_window
node_window -->|"hosts controls"| node_controls
node_window -->|"uses stream client"| node_camera_stream
node_window -->|"runs detection"| node_motion
node_window -->|"sends commands"| node_mqtt_manager
node_window -->|"updates display"| node_video_view
node_camera_stream -->|"requests MJPEG"| node_camera_service
node_camera_stream -.->|"yields frames"| node_motion
node_motion -->|"reads thresholds"| node_settings
node_mqtt_manager -->|"connects and publishes"| node_mqtt_broker
node_mqtt_manager -->|"subscribes to status"| node_mqtt_broker
node_window -->|"records activity"| node_statistics
node_statistics -->|"exports report"| node_pdf_export
node_camera_firmware -.->|"provides camera driver"| node_firmware_app

click node_launcher "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/main.py"
click node_window "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/main_window.py"
click node_controls "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/control_panel.py"
click node_settings "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/config/settings.py"
click node_camera_stream "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/core/camera.py"
click node_motion "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/core/detector.py"
click node_video_view "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/video_display.py"
click node_camera_firmware "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/esp32_camera_mjpeg/src/OV2640.cpp"
click node_firmware_app "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/esp32_camera_mjpeg/esp32_camera_mjpeg.ino"
click node_mqtt_manager "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/core/mqtt_client.py"
click node_statistics "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/stats_tab.py"
click node_pdf_export "https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/utils/pdf_export.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_launcher,node_window,node_controls,node_settings toneBlue
class node_camera_stream,node_motion,node_video_view toneAmber
class node_camera_service,node_camera_firmware,node_firmware_app,node_mqtt_manager toneMint
class node_statistics,node_pdf_export toneRose
class node_operator,node_mqtt_broker toneIndigo
```

## Components

### Desktop application

- [Application launcher](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/main.py): `main.py`
- [Main window](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/main_window.py): `ui/main_window.py`
- [Control panel](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/control_panel.py): `ui/control_panel.py`
- [Runtime settings](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/config/settings.py): `config/settings.py`

### Video and detection

- [MJPEG stream client](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/core/camera.py): `core/camera.py`
- [Motion detector](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/core/detector.py): `core/detector.py`
- [Video display](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/video_display.py): `ui/video_display.py`

### Camera device

- **ESP32 camera stream**
- [OV2640 driver](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/esp32_camera_mjpeg/src/OV2640.cpp): `esp32_camera_mjpeg/src/OV2640.cpp`
- [Camera firmware app](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/esp32_camera_mjpeg/esp32_camera_mjpeg.ino): `esp32_camera_mjpeg/esp32_camera_mjpeg.ino`
- [MQTT manager](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/core/mqtt_client.py): `core/mqtt_client.py`

### Session reporting

- [Session statistics](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/ui/stats_tab.py): `ui/stats_tab.py`
- [PDF report exporter](https://github.com/ilyakolos777/esp32-cam-security-system/blob/main/utils/pdf_export.py): `utils/pdf_export.py`

### Other components

- **Operator**
- **MQTT broker**

## Connections

- Operator → Application launcher: starts app (evidence: `main.py`)
- Application launcher → Runtime settings: reads settings (evidence: `main.py`)
- Application launcher → Main window: creates window (evidence: `main.py`)
- Main window → Control panel: hosts controls (evidence: `ui/main_window.py`)
- Main window → MJPEG stream client: uses stream client (evidence: `ui/main_window.py`)
- Main window → Motion detector: runs detection (evidence: `ui/main_window.py`)
- Main window → MQTT manager: sends commands (evidence: `ui/main_window.py`)
- Main window → Video display: updates display (evidence: `ui/main_window.py`)
- MJPEG stream client → ESP32 camera stream: requests MJPEG (evidence: `core/camera.py`)
- MJPEG stream client → Motion detector: yields frames
- Motion detector → Runtime settings: reads thresholds (evidence: `core/detector.py`)
- MQTT manager → MQTT broker: connects and publishes (evidence: `core/mqtt_client.py`)
- MQTT manager → MQTT broker: subscribes to status (evidence: `core/mqtt_client.py`)
- Main window → Session statistics: records activity (evidence: `ui/main_window.py`)
- Session statistics → PDF report exporter: exports report (evidence: `ui/stats_tab.py`)
- OV2640 driver → Camera firmware app: provides camera driver
