# sayedgamal99/real-time-smoke-fire-detection-yolo11 architecture

> Architecture diagram of the GitHub repository sayedgamal99/real-time-smoke-fire-detection-yolo11, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sayedgamal99/real-time-smoke-fire-detection-yolo11
- Repository: https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11

## Overview

1. **Repository purpose**
   - This is a Python-based **real-time smoke/fire detection system** built around a **YOLOv11 object detection model**.
   - The core runtime takes image/video input, detects `Fire` and `Smoke`, and then triggers alerts through messaging channels.

2. **Primary runtime path**
   - The main execution path is centered in `src/main.py`.
   - That entry point likely wires together:
     - model loading,
     - frame/video ingestion,
     - detection post-processing,
     - alerting/notification dispatch.
   - `src/fire_detector.py` is the main detection domain module.

3. **Detection subsystem**
   - `src/fire_detector.py` is the core inference boundary.
   - It likely encapsulates:
     - loading YOLO weights from `models/`,
     - running inference on frames/images/videos,
     - filtering detections by confidence/IOU,
     - formatting detection results for downstream use.
   - The repository ships several pretrained weights, with `models/best_nano_111.pt` appearing to be the default small production-oriented model.

4. **Alerting / notification subsystem**
   - `src/notification_service.py` is the notification boundary for external alerts.
   - From the README and file naming, this service is intended to send detection evidence to messaging platforms such as **Telegram** and possibly **WhatsApp**.
   - The system is therefore not just a detector; it is an **event-driven safety monitor** that turns detections into outbound notifications.

5. **Bot integration**
   - `src/bot.py` suggests a Telegram bot integration layer, separate from the core detector.
   - This implies a split between:
     - detection logic,
     - messaging/bot transport,
     - possibly user interaction or command handling.
   - Keeping bot code separate from detection code is an important architectural boundary.

6. **Configuration and user gating**
   - `src/config.py` holds runtime configuration, likely including model paths, confidence thresholds, API tokens, and channel-specific settings.
   - `src/check_users.py` indicates some form of **access control or recipient validation**, probably to ensure only approved users receive bot notifications or can interact with the service.

7. **Data flow**
   - Input sources include sample media in `data/` and live camera/webcam sources described in the README.
   - Frames are processed by the detector, detections are written or copied to an output area such as `detected_fires/`, and then notification payloads are sent through the messaging layer.
   - The key pipeline is: **video/image input → YOLO detection → event classification as fire/smoke → evidence capture → notification**.

8. **Model and experiment assets**
   - `models/` contains multiple trained YOLO weights at different sizes (`nano`, `small`, `medium`, `large`) and a Kaggle-developed set.
   - This suggests the architecture supports **model swapping** for different latency/accuracy tradeoffs.
   - The README emphasizes real-time performance, so smaller models are likely used for deployment, while larger ones are available for experimentation.

9. **Frontend / presentation layer**
   - `index.html` and `styles.css` indicate a simple static presentation layer.
   - This is likely used as a landing page or demo page rather than the main runtime.
   - It is architecturally separate from detection/notification logic and does not appear to be the core product surface.

10. **Generated outputs**
   - `detected_fires/` is an output artifact area, probably storing captured images or annotated frames when a fire/smoke event is detected.
   - This folder supports human verification and provides the visual evidence attached to alerts.

11. **Training and notebooks**
   - `notebook/smoke-fire-detection-yolo11.ipynb` captures the training/experimentation workflow.
   - This notebook is an offline ML development asset, distinct from the production inference path.
   - The repository therefore has both **model development** and **model serving/inference** concerns, but they are kept in separate areas.

12. **Testing structure**
   - `tests/` covers detector behavior, notification behavior, integration paths, and label/data cleanup utilities.
   - The presence of `tests/test_data/` with label edge cases suggests validation around dataset preprocessing and annotation correctness.
   - This test suite protects both ML-adjacent logic and the notification pipeline, which is important for a system that depends on external alerts.

13. **External dependencies and runtime profile**
   - The project is Python-based and uses **Ultralytics YOLOv11** as the key ML runtime.
   - The README also references Telegram and WhatsApp integrations, so the system depends on external messaging APIs/services.
   - That means the architecture has two critical external boundaries: **model inference** and **messaging delivery**.

14. **Overall architectural shape**
   - Conceptually, this is a **single-machine inference service with outbound alerting**, not a distributed backend.
   - The major subsystems are:
     - inference engine,
     - alert/notification layer,
     - configuration/access control,
     - model/data assets,
     - offline training notebooks,
     - tests and validation fixtures.
   - For an architecture diagram, the main emphasis should be on the **real-time media processing pipeline** and its **notification side effects**.

Main entry points: [`src/fire_detector.py`](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/fire_detector.py) (Detector), [`src/main.py`](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/main.py) (Main), [`tests/test_integration.py`](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_integration.py) (Test Suite), [`src/notification_service.py`](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/notification_service.py) (Alerts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entry["Main<br/>entrypoint<br/>[main.py]"]
  node_cfg["Config<br/>settings<br/>[config.py]"]
  node_detector["Detector<br/>inference<br/>[fire_detector.py]"]
  node_notif["Alerts<br/>notification"]
  node_bot["Bot<br/>messaging<br/>[bot.py]"]
  node_users["Users<br/>access control<br/>[check_users.py]"]
  node_web["Landing Page<br/>presentation<br/>[index.html]"]
end

subgraph group_assets["Assets"]
  node_input["Video Input<br/>media source<br/>[video.mp4]"]
  node_firevid["Fire Clips<br/>media source<br/>[gen_fire.mp4]"]
  node_weights[("Default Weights<br/>model weights<br/>[best_nano_111.pt]")]
  node_altweights[("Model Variants<br/>model weights<br/>[best_small.pt]")]
  node_evidence["Detected Fires<br/>output artifact<br/>[README.md]"]
end

subgraph group_dev["Offline ML"]
  node_notebook["Notebook"]
end

subgraph group_tests["Tests"]
  node_testsuite["Test Suite<br/>tests"]
  node_detector_tests["Detector Tests"]
  node_notif_tests["Alert Tests"]
  node_fixture["Label Fixtures<br/>test data<br/>[test_valid.txt]"]
end

node_entry -->|"loads"| node_cfg
node_entry -->|"starts"| node_detector
node_entry -->|"connects"| node_notif
node_entry -->|"routes"| node_bot
node_detector -->|"uses"| node_weights
node_detector -.->|"can swap"| node_altweights
node_entry -->|"reads"| node_input
node_input -->|"frames"| node_detector
node_firevid -.->|"examples"| node_detector
node_detector -->|"writes"| node_evidence
node_detector -->|"triggers"| node_notif
node_notif -->|"dispatches"| node_bot
node_bot -->|"verifies"| node_users
node_notebook -.->|"produces"| node_weights
node_testsuite -->|"covers"| node_detector_tests
node_testsuite -->|"covers"| node_notif_tests
node_testsuite -->|"uses"| node_fixture
node_web -.->|"presents"| node_entry

click node_entry "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/main.py"
click node_cfg "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/config.py"
click node_detector "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/fire_detector.py"
click node_notif "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/notification_service.py"
click node_bot "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/bot.py"
click node_users "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/check_users.py"
click node_input "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/data/video.mp4"
click node_firevid "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/data/gen_fire.mp4"
click node_weights "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/models/best_nano_111.pt"
click node_altweights "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/models/kaggle developed models/best_small.pt"
click node_evidence "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/detected_fires/README.md"
click node_notebook "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/notebook/smoke-fire-detection-yolo11.ipynb"
click node_testsuite "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_integration.py"
click node_detector_tests "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_fire_detector.py"
click node_notif_tests "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_notification_service.py"
click node_fixture "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_data/train/labels/test_valid.txt"
click node_web "https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/index.html"

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_entry,node_cfg,node_detector,node_notif,node_bot,node_users,node_web toneBlue
class node_input,node_firevid,node_weights,node_altweights,node_evidence toneAmber
class node_notebook toneMint
class node_testsuite,node_detector_tests,node_notif_tests,node_fixture toneRose
```

## Components

### Runtime

Real-time detection and alerting path

- [Main](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/main.py): entrypoint · Application entrypoint wiring the live pipeline · `src/main.py`
- [Config](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/config.py): settings · Runtime thresholds, paths, and credentials · `src/config.py`
- [Detector](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/fire_detector.py): inference · YOLO-based fire and smoke inference boundary · `src/fire_detector.py`
- [Alerts](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/notification_service.py): notification · Outbound notification service for detections · `src/notification_service.py`
- [Bot](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/bot.py): messaging · Telegram-facing transport and command layer · `src/bot.py`
- [Users](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/src/check_users.py): access control · Recipient validation and user gating · `src/check_users.py`
- [Landing Page](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/index.html): presentation · Static demo or informational front end · `index.html`

### Assets

Models, sample media, and generated evidence

- [Video Input](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/data/video.mp4): media source · Sample video and live camera inputs · `data/video.mp4`
- [Fire Clips](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/data/gen_fire.mp4): media source · Example fire-bearing video assets · `data/gen_fire.mp4`
- [Default Weights](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/models/best_nano_111.pt): model weights · Primary production-oriented YOLO model · `models/best_nano_111.pt`
- [Model Variants](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/HEAD/models/kaggle%20developed%20models/best_small.pt): model weights · Alternative YOLO checkpoints for tradeoffs · `models/kaggle developed models/best_small.pt`
- [Detected Fires](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/detected_fires/README.md): output artifact · Annotated frames and captured evidence for review · `detected_fires/README.md`

### Offline ML

Training and experimentation workflow

- [Notebook](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/notebook/smoke-fire-detection-yolo11.ipynb): training notebook · Offline training and experimentation workflow · `notebook/smoke-fire-detection-yolo11.ipynb`

### Tests

Validation and regression coverage

- [Test Suite](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_integration.py): tests · Core regression tests for detection and notifications · `tests/test_integration.py`
- [Detector Tests](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_fire_detector.py): tests · Focused coverage for inference behavior · `tests/test_fire_detector.py`
- [Alert Tests](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_notification_service.py): tests · Coverage for notification delivery logic · `tests/test_notification_service.py`
- [Label Fixtures](https://github.com/sayedgamal99/real-time-smoke-fire-detection-yolo11/blob/main/tests/test_data/train/labels/test_valid.txt): test data · Edge-case annotation data for cleanup validation · `tests/test_data/train/labels/test_valid.txt`

## Connections

- Main → Config: loads · Reads runtime configuration and paths
- Main → Detector: starts · Creates the inference pipeline
- Main → Alerts: connects · Initializes outbound alerting
- Main → Bot: routes · Wires messaging transport into the app
- Detector → Default Weights: uses · Loads the default YOLO checkpoint
- Detector → Model Variants: can swap · Supports alternate model sizes
- Main → Video Input: reads · Consumes video or camera frames
- Video Input → Detector: frames · Supplies media to inference
- Fire Clips → Detector: examples · Representative fire scenarios for evaluation
- Detector → Detected Fires: writes · Stores annotated captures and event evidence
- Detector → Alerts: triggers · Emits fire/smoke events for alerting
- Alerts → Bot: dispatches · Sends alerts through the bot transport
- Bot → Users: verifies · Checks who may receive or use notifications
- Notebook → Default Weights: produces · Trains or evaluates model checkpoints
- Test Suite → Detector Tests: covers · Regression coverage includes detector behavior
- Test Suite → Alert Tests: covers · Regression coverage includes alerting behavior
- Test Suite → Label Fixtures: uses · Uses label edge cases and cleanup fixtures
- Landing Page → Main: presents · Static surface separate from the runtime pipeline
