# aksh1810/fire-detection architecture

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

- Interactive diagram: https://gitdiagram.com/aksh1810/fire-detection
- Repository: https://github.com/aksh1810/fire-detection

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **single-repo Python computer vision application** centered around a **YOLOv8 (Ultralytics) object detection model** to detect **Fire** and **Smoke**. It has two runtime/inference entrypoints (webcam + image) and a separate training + dataset acquisition toolchain.

In other words, you’re not drawing a typical multi-service web architecture. The “system” is a **client-side/edge runtime** (camera/image → model inference → alert/overlay) plus an **offline ML pipeline** (download dataset → train → produce weights → run inference).

##### Runtime / inference (operational system)
- `detect_fire.py`
- `detect_fire_image.py`
**Single image** load → YOLOv8 inference → visualization/alert.

##### Training / ML pipeline (build system for the model)
- `train_fire.py`
YOLOv8 training/fine-tuning using **PyTorch/Ultralytics**, reading dataset config from `data.yaml`, producing trained weights.
- `data.yaml`
Dataset configuration (paths, class names: Fire/Smoke). Critical “config artifact” in the training pipeline.
- `Fire_Detection_Colab.ipynb`
Alternative execution environment for training (Google Colab GPU). Architecturally, it’s another “runner” for the same training pipeline.
- `download_dataset.py` + `download_manual.py`
Dataset acquisition utilities (notably **Roboflow** per README). These are “ingestion” components feeding training data.

##### Build/runtime dependencies
- `requirements.txt`
Pins runtime/training deps: Ultralytics (YOLOv8), OpenCV, PyTorch, etc. Represent as a “Dependency Layer” or annotate components with these techs.

##### What the README adds (relationships + non-code components)
The README clarifies:
- **Inputs**: webcam frames OR static image
- **Core processing**: YOLOv8 model inference
- **Training**: uses Roboflow dataset sources; can run locally or in Colab

- **Roboflow Universe / dataset hosting** (external)
- **Local machine hardware** (CPU, optional GPU)
- **Webcam device / file system** (image source)
- **Audio output device** (speaker/beeper)

##### Important architectural patterns/design principles to highlight (specific to this repo)
- **Edge/Local inference**: the “deployment target” is a local machine, not a server.
- **Two-mode input adapters**: webcam vs file input are separate entrypoints but share the same core inference pipeline.
- **Model-as-artifact**: trained weights are the central contract between training and inference.
- **Externalized dataset configuration**: `data.yaml` is the training-time contract to dataset layout + class names.

- **OpenCV**: capture + display
- **Ultralytics YOLOv8**: inference + training APIs
- **PyTorch**: underlying framework
- **Roboflow**: dataset source/management
- **Google Colab**: optional training runtime with GPU
- **Python 3.8+**: runtime

An environment note:
- “Runs on CPU ~30 FPS; optional GPU for training/inference”

User ↔ App; Webcam/Image → App; App → Audio/Display; Roboflow → Dataset Download; Colab → Training.
Roboflow → download scripts → dataset/labels → train_fire.py/Colab → weights artifact.
##### Runtime Inference Sequence/Dataflow (1 page)
Webcam loop (frame-by-frame) and/or image path; show threshold decision leading to beep.

That will be the most accurate architecture representation for this project: it captures the operational detection system and the lifecycle path that produces the model it depends on.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% System Context (Top)
  %% =========================
  subgraph "System Context (Edge/Local App + Offline ML Pipeline)"
    U["User / Operator"]:::external

    HW["Local Machine (CPU; optional GPU)"]:::device
    CAM["Webcam Device"]:::device
    IMG["Image Files (on disk)"]:::data
    SPK["Audio Output (Speaker/Beeper)"]:::device
    DISP["Display (OpenCV window)"]:::device

    RF(("Roboflow Universe (Dataset Hosting)")):::cloud
    COLAB(("Google Colab (GPU Training Runtime)")):::cloud

    REPO["Fire/Smoke Detection Repo (Python 3.8+)"]:::app
  end

  U -.->|"start/stop_scripts"| REPO
  REPO -.->|"runs_on"| HW

  CAM -->|"frames"| REPO
  IMG -->|"pixels"| REPO
  REPO -->|"beep_alert"| SPK
  REPO -->|"rendered_overlay"| DISP

  RF -->|"dataset_images+labels"| REPO
  COLAB <-->|"executes_notebook"| REPO

  %% =========================
  %% Offline Training / Data Build (Middle)
  %% =========================
  subgraph "Offline Training & Dataset Acquisition (Build Path)"
    DL1["download_dataset.py (Roboflow ingestion)"]:::script
    DL2["download_manual.py (Manual dataset helper)"]:::script

    DATASET[("Dataset on Disk (images/labels)")]:::data
    DATAYAML[["data.yaml (Dataset config: Fire/Smoke)"]]:::artifact

    TRAIN["train_fire.py (Ultralytics YOLOv8 training)"]:::script
    NB["Fire_Detection_Colab.ipynb (Colab training runner)"]:::script

    ENGINE_TRAIN["Ultralytics YOLOv8 Training API (PyTorch)"]:::engine
    W_TRAINED[("Trained Weights Artifact (weights.pt)")]:::data
  end

  RF -->|"download"| DL1
  RF -.->|"optional_manual_export"| DL2

  DL1 -->|"writes"| DATASET
  DL2 -->|"writes"| DATASET

  DATASET -->|"paths+labels"| TRAIN
  DATAYAML -->|"dataset_contract"| TRAIN
  TRAIN -->|"calls"| ENGINE_TRAIN
  ENGINE_TRAIN -->|"outputs"| W_TRAINED

  COLAB -->|"runs"| NB
  NB -->|"uses"| DATAYAML
  NB -->|"reads"| DATASET
  NB -->|"calls"| ENGINE_TRAIN
  NB -->|"outputs"| W_TRAINED

  %% =========================
  %% Online Inference (Bottom)
  %% =========================
  subgraph "Online Inference (Runtime Path)"
    REQ[["requirements.txt (Deps: ultralytics, opencv, torch, etc.)"]]:::artifact

    R1["detect_fire.py (Webcam inference runner)"]:::script
    R2["detect_fire_image.py (Single-image inference runner)"]:::script

    CAP["Capture/Input Adapter (OpenCV VideoCapture / imread)"]:::engine
    PRE["Pre-processing (resize/format)"]:::engine
    INF["YOLOv8 Inference Engine (Ultralytics + PyTorch)"]:::engine
    POST["Post-processing + Visualization (boxes/labels/conf)"]:::engine
    ALERT["Alerting Module (threshold -> beep)"]:::engine
    OUT["Output (OpenCV imshow / saved image)"]:::engine

    W_LOAD[("Model Weights (pretrained or trained)")]:::data
  end

  %% Entrypoints
  CAM -->|"frames"| R1
  IMG -->|"image_path"| R2

  R1 -->|"uses"| CAP
  R2 -->|"uses"| CAP

  CAP -->|"ndarray/frame"| PRE
  PRE -->|"tensor/array"| INF
  W_LOAD -.->|"loads_weights"| INF
  INF -->|"detections"| POST
  POST -->|"overlay"| OUT
  POST -->|"fire/smoke_detected"| ALERT
  ALERT -->|"audio_beep"| SPK
  OUT -->|"display"| DISP

  %% Bridge: training -> inference
  W_TRAINED -.->|"deploy/load"| W_LOAD

  %% Repo aggregation (context -> internals)
  REPO -->|"offline_tools"| DL1
  REPO -->|"offline_tools"| DL2
  REPO -->|"training"| TRAIN
  REPO -->|"runtime"| R1
  REPO -->|"runtime"| R2
  REPO -.->|"dependencies"| REQ

  %% =========================
  %% Notes / Principles
  %% =========================
  NOTE1["Pattern: Model-as-artifact boundary (weights.pt) connects training -> inference"]:::note
  NOTE2["Design: Two-mode input adapters (webcam vs image) share the same core pipeline"]:::note
  NOTE3["Env: Edge/local inference; training typically benefits from GPU (local or Colab)"]:::note

  W_TRAINED -.->|"contract"| NOTE1
  R1 -.->|"shared_pipeline"| NOTE2
  R2 -.->|"shared_pipeline"| NOTE2
  HW -.->|"runtime_note"| NOTE3
  COLAB -.->|"training_note"| NOTE3

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click R1 "https://github.com/aksh1810/fire-detection/blob/main/detect_fire.py"
  click R2 "https://github.com/aksh1810/fire-detection/blob/main/detect_fire_image.py"
  click TRAIN "https://github.com/aksh1810/fire-detection/blob/main/train_fire.py"
  click DATAYAML "https://github.com/aksh1810/fire-detection/blob/main/data.yaml"
  click NB "https://github.com/aksh1810/fire-detection/blob/main/Fire_Detection_Colab.ipynb"
  click DL1 "https://github.com/aksh1810/fire-detection/blob/main/download_dataset.py"
  click DL2 "https://github.com/aksh1810/fire-detection/blob/main/download_manual.py"
  click REQ "https://github.com/aksh1810/fire-detection/blob/main/requirements.txt"
  click REPO "https://github.com/aksh1810/fire-detection/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef script fill:#1f77b4,stroke:#0b3d91,color:#ffffff,stroke-width:1.5px
  classDef engine fill:#ff7f0e,stroke:#a64b00,color:#ffffff,stroke-width:1.5px
  classDef data fill:#2ca02c,stroke:#145a14,color:#ffffff,stroke-width:1.5px
  classDef artifact fill:#2ca02c,stroke:#145a14,color:#ffffff,stroke-width:1.5px,stroke-dasharray:4 3
  classDef device fill:#7f7f7f,stroke:#4d4d4d,color:#ffffff,stroke-width:1.5px
  classDef cloud fill:#9467bd,stroke:#4b2e83,color:#ffffff,stroke-width:1.5px
  classDef app fill:#17becf,stroke:#0b6a73,color:#ffffff,stroke-width:1.5px
  classDef external fill:#111827,stroke:#374151,color:#ffffff,stroke-width:1.5px
  classDef note fill:#fff3cd,stroke:#d39e00,color:#1f2937,stroke-width:1.2px
```
