# kabitacodeforge/industrial-ai-vision architecture

> Architecture diagram of the GitHub repository kabitacodeforge/industrial-ai-vision, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kabitacodeforge/industrial-ai-vision
- Repository: https://github.com/kabitacodeforge/industrial-ai-vision

## Overview

1. **What this repository is**
   - This is an **industrial PPE compliance system** centered on **real-time video inference**. The core job is to detect people and safety gear such as **helmets, vests, and boots** from webcam or video input, then turn those detections into operational safety signals.

2. **Primary runtime path**
   - The main data path starts in the **vision layer**: frames are captured from a camera or stream, passed through YOLO-based detection, and then annotated with overlays such as bounding boxes, FPS, timestamps, and status markers.
   - The README emphasizes a standalone detection experience, while the file tree shows a broader system around that pipeline.

3. **Vision subsystem**
   - `vision/camera.py` handles frame acquisition from physical cameras or video sources.
   - `vision/stream.py` likely manages continuous streaming and frame delivery.
   - `vision/detector.py` and `vision/yolo_engine.py` form the inference boundary, wrapping the Ultralytics YOLO model in `models/yolov8n.pt`.
   - This layer is the main compute-heavy component and is where OpenCV and YOLO are directly used.

4. **Model asset boundary**
   - `models/yolov8n.pt` is the packaged detector weight file.
   - That makes the model an embedded local dependency rather than a remote service, so inference is likely done in-process on CPU or GPU depending on availability.

5. **Core orchestration**
   - `core/factory_loop.py` appears to be the central runtime loop that ties vision output to business logic.
   - `core/state.py` likely holds shared runtime state for the current frame, detection status, and system status.
   - `core/decision_engine.py` converts raw detections into compliance decisions or safety events.
   - `core/alerts.py` likely handles alarm/notification logic when violations are detected.
   - `core/analytics.py` aggregates metrics over time, such as detection counts, compliance rates, or throughput.
   - `core/predictor.py` suggests some forecasting or trend estimation on top of the live data.

6. **Agent layer**
   - The `agents/` directory indicates a higher-level abstraction above raw vision and core logic.
   - `agents/vision_agent.py` likely wraps visual analysis tasks.
   - `agents/safety_agent.py` likely focuses on PPE compliance interpretation and safety rule enforcement.
   - `agents/prediction_agent.py` likely consumes historical or current signals to forecast outcomes.
   - `agents/energy_agent.py` suggests a separate operational concern, possibly monitoring or optimizing resource usage.
   - These agents imply a modular, decision-oriented design rather than a single monolithic detector.

7. **Persistence and operational state**
   - `core/database.py` and `factory.db` show a local persistence layer, likely for events, detections, analytics summaries, or system state snapshots.
   - This means the system is not purely transient; it retains operational history for dashboards or audits.
   - The database is a local SQLite-style artifact rather than an external managed datastore, based on the presence of a single `.db` file.

8. **API and application entrypoints**
   - `api/main.py` is likely the service-facing entrypoint for programmatic access to detections, metrics, or alert data.
   - `app/main.py` appears to be a separate application entrypoint, possibly for the main runtime or UI service.
   - The presence of multiple entrypoints suggests the system can be run as a detector, as an API service, and as a user-facing app.

9. **Dashboard/UI layer**
   - `dashboard/app.py` is a distinct presentation boundary for visualizing system status, compliance, and analytics.
   - This layer likely reads from the core/database/API rather than directly from the camera pipeline, which keeps visualization decoupled from inference.

10. **End-to-end data flow**
   - Camera/video input enters the vision subsystem.
   - YOLO detection produces structured objects like person/PPE detections.
   - Core logic evaluates compliance, updates state, triggers alerts, and writes records.
   - Analytics and predictor components summarize or forecast behavior.
   - API/dashboard layers expose the resulting information to users or other systems.

11. **Key architectural separation**
   - The repository cleanly separates **perception** (`vision/`), **decision-making** (`core/`), **specialized agents** (`agents/`), and **presentation/integration** (`api/`, `dashboard/`, `app/`).
   - That separation matters for an architecture diagram because the frame stream, business logic, persistence, and UI are distinct concerns.

12. **Deployment/runtime hints**
   - `requirements.txt` and the README point to a Python runtime using **OpenCV** and **Ultralytics YOLO**.
   - The README notes **GPU acceleration with CUDA** as optional, with CPU fallback, so inference is designed to run locally across different hardware profiles.
   - `render.yaml` indicates the project has at least one cloud deployment target or hosting configuration.

13. **What to emphasize in a diagram**
   - Show the camera/video stream as the input source.
   - Show the YOLO model as the inference engine inside the vision boundary.
   - Show core decisioning/alerts/database as the processing and persistence layer.
   - Show API/dashboard/app as consumers of stored or live system state.
   - Show agents as orchestration or specialization layers above the core logic.

14. **Overall shape**
   - This is best represented as a **real-time edge AI pipeline with operational control layers**, not just a computer vision demo.
   - The main technical boundary is between the **high-frequency frame processing path** and the **slower state, analytics, and presentation path**.

Main entry points: [`core/factory_loop.py`](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/factory_loop.py) (Factory loop), [`core/database.py`](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/database.py) (Database), [`vision/detector.py`](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/detector.py) (Detector), [`core/decision_engine.py`](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/decision_engine.py) (Decision engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Vision"]
  node_vision_camera["Camera<br/>frame source<br/>[camera.py]"]
  node_vision_stream["Stream<br/>frame pipeline<br/>[stream.py]"]
  node_vision_detector["Detector<br/>detection wrapper<br/>[detector.py]"]
  node_vision_yolo["YOLO engine<br/>inference backend<br/>[yolo_engine.py]"]
  node_model_weights["YOLO weights<br/>model artifact<br/>[yolov8n.pt]"]
end

subgraph group_core["Core"]
  node_core_loop["Factory loop<br/>runtime loop<br/>[factory_loop.py]"]
  node_core_state["State<br/>[state.py]"]
  node_core_decision["Decision engine<br/>policy logic<br/>[decision_engine.py]"]
  node_core_alerts["Alerts<br/>notification logic<br/>[alerts.py]"]
  node_core_analytics["Analytics<br/>metrics aggregation<br/>[analytics.py]"]
  node_core_predictor["Predictor<br/>forecasting<br/>[predictor.py]"]
  node_core_db[("Database<br/>local persistence<br/>[database.py]")]
  node_factory_db["factory.db<br/>sqlite data file<br/>[factory.db]"]
end

subgraph group_agents["Agents"]
  node_agent_vision["Vision agent<br/>[vision_agent.py]"]
  node_agent_safety["Safety agent<br/>[safety_agent.py]"]
  node_agent_prediction["Prediction agent"]
  node_agent_energy["Energy agent<br/>[energy_agent.py]"]
end

subgraph group_interfaces["Interfaces"]
  node_api_main["API<br/>service entrypoint<br/>[main.py]"]
  node_app_main["App<br/>runtime entrypoint<br/>[main.py]"]
  node_dashboard_app["Dashboard<br/>ui entrypoint<br/>[app.py]"]
end

node_vision_camera -->|"frames"| node_vision_stream
node_vision_stream -->|"frames"| node_vision_detector
node_vision_detector -->|"infer"| node_vision_yolo
node_vision_yolo -->|"loads"| node_model_weights
node_vision_detector -->|"detections"| node_core_loop
node_core_loop -->|"updates"| node_core_state
node_core_loop -->|"evaluates"| node_core_decision
node_core_decision -->|"triggers"| node_core_alerts
node_core_decision -->|"records"| node_core_db
node_core_alerts -->|"logs"| node_core_db
node_core_loop -->|"metrics"| node_core_analytics
node_core_analytics -->|"features"| node_core_predictor
node_core_db -->|"writes"| node_factory_db
node_agent_vision -->|"uses"| node_vision_detector
node_agent_safety -->|"uses"| node_core_decision
node_agent_safety -->|"uses"| node_core_alerts
node_agent_prediction -->|"uses"| node_core_predictor
node_agent_energy -->|"reads"| node_core_state
node_api_main -->|"reads"| node_core_db
node_api_main -->|"serves"| node_core_analytics
node_dashboard_app -->|"reads"| node_core_db
node_dashboard_app -->|"shows"| node_core_analytics
node_app_main -->|"starts"| node_core_loop
node_app_main -.->|"may host"| node_api_main

click node_vision_camera "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/camera.py"
click node_vision_stream "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/stream.py"
click node_vision_detector "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/detector.py"
click node_vision_yolo "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/yolo_engine.py"
click node_model_weights "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/models/yolov8n.pt"
click node_core_loop "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/factory_loop.py"
click node_core_state "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/state.py"
click node_core_decision "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/decision_engine.py"
click node_core_alerts "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/alerts.py"
click node_core_analytics "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/analytics.py"
click node_core_predictor "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/predictor.py"
click node_core_db "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/database.py"
click node_factory_db "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/factory.db"
click node_agent_vision "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/agents/vision_agent.py"
click node_agent_safety "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/agents/safety_agent.py"
click node_agent_prediction "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/agents/prediction_agent.py"
click node_agent_energy "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/agents/energy_agent.py"
click node_api_main "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/api/main.py"
click node_app_main "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/app/main.py"
click node_dashboard_app "https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/dashboard/app.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_vision_camera,node_vision_stream,node_vision_detector,node_vision_yolo,node_model_weights toneBlue
class node_core_loop,node_core_state,node_core_decision,node_core_alerts,node_core_analytics,node_core_predictor,node_core_db,node_factory_db toneAmber
class node_agent_vision,node_agent_safety,node_agent_prediction,node_agent_energy toneMint
class node_api_main,node_app_main,node_dashboard_app toneRose
```

## Components

### Vision

Frame capture, streaming, and YOLO inference

- [Camera](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/camera.py): frame source · Captures frames from camera or video input · `vision/camera.py`
- [Stream](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/stream.py): frame pipeline · Maintains continuous frame delivery · `vision/stream.py`
- [Detector](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/detector.py): detection wrapper · Coordinates object detection on incoming frames · `vision/detector.py`
- [YOLO engine](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/vision/yolo_engine.py): inference backend · Wraps Ultralytics YOLO for in-process inference · `vision/yolo_engine.py`
- [YOLO weights](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/models/yolov8n.pt): model artifact · Packaged detector weights used by the inference engine · `models/yolov8n.pt`

### Core

Decisioning, alerts, analytics, and persistence

- [Factory loop](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/factory_loop.py): runtime loop · Main runtime loop connecting vision output to business logic · `core/factory_loop.py`
- [State](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/state.py): shared runtime state · Holds current frame, status, and operational state · `core/state.py`
- [Decision engine](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/decision_engine.py): policy logic · Turns detections into compliance decisions and events · `core/decision_engine.py`
- [Alerts](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/alerts.py): notification logic · Emits alarms or violation notifications · `core/alerts.py`
- [Analytics](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/analytics.py): metrics aggregation · Aggregates detection and compliance metrics over time · `core/analytics.py`
- [Predictor](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/predictor.py): forecasting · Produces trend or outcome predictions from system signals · `core/predictor.py`
- [Database](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/core/database.py): local persistence · Stores events, summaries, and operational history · `core/database.py`
- [factory.db](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/factory.db): sqlite data file · Local database artifact for persisted records · `factory.db`

### Agents

Specialized orchestration layers

- [Vision agent](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/agents/vision_agent.py): agent · Higher-level wrapper for visual analysis tasks · `agents/vision_agent.py`
- [Safety agent](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/agents/safety_agent.py): agent · Interprets PPE compliance and safety rules · `agents/safety_agent.py`
- [Prediction agent](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/agents/prediction_agent.py): agent · Consumes signals for forecasting and trend estimation · `agents/prediction_agent.py`
- [Energy agent](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/agents/energy_agent.py): agent · Handles operational or resource-efficiency concerns · `agents/energy_agent.py`

### Interfaces

Service and dashboard entrypoints

- [API](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/api/main.py): service entrypoint · Programmatic access to detections, metrics, or alerts · `api/main.py`
- [App](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/app/main.py): runtime entrypoint · Primary application entrypoint for running the system · `app/main.py`
- [Dashboard](https://github.com/kabitacodeforge/industrial-ai-vision/blob/main/dashboard/app.py): ui entrypoint · Presentation layer for status, compliance, and analytics · `dashboard/app.py`

## Connections

- Camera → Stream: frames · Raw frames flow into the stream pipeline
- Stream → Detector: frames · Continuous frames are handed to detection
- Detector → YOLO engine: infer · Detector delegates inference to the YOLO engine
- YOLO engine → YOLO weights: loads · Inference engine uses packaged model weights
- Detector → Factory loop: detections · Structured detections feed the main runtime loop
- Factory loop → State: updates · Loop maintains shared operational state
- Factory loop → Decision engine: evaluates · Runtime loop passes detections into policy logic
- Decision engine → Alerts: triggers · Policy outcomes can emit alerts
- Decision engine → Database: records · Decisions and events are persisted
- Alerts → Database: logs · Alerts are stored for audit and history
- Factory loop → Analytics: metrics · Operational signals feed analytics
- Analytics → Predictor: features · Historical metrics support forecasting
- Database → factory.db: writes · Persistence targets the local database file
- Vision agent → Detector: uses · Vision agent consumes detection capabilities
- Safety agent → Decision engine: uses · Safety agent relies on compliance logic
- Safety agent → Alerts: uses · Safety agent can surface violations
- Prediction agent → Predictor: uses · Prediction agent wraps forecasting behavior
- Energy agent → State: reads · Energy agent uses runtime state signals
- API → Database: reads · API exposes persisted operational data
- API → Analytics: serves · API can expose metrics and summaries
- Dashboard → Database: reads · Dashboard visualizes stored history and status
- Dashboard → Analytics: shows · Dashboard renders analytics views
- App → Factory loop: starts · Application entrypoint launches the runtime loop
- App → API: may host · App can coexist with or launch the API surface