# montero52/vision-activity-analytics architecture

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

- Interactive diagram: https://gitdiagram.com/montero52/vision-activity-analytics
- Repository: https://github.com/montero52/vision-activity-analytics

## Overview

From the file tree + README, this is a **single-node, edge-deployed computer-vision analytics system** with a **Flask web dashboard** that drives two execution modes:

- **Live (streaming / preview) pipeline**: camera/video stream → YOLOv8(OpenVINO) inference → tracking + seat-based spatial logic → on-screen/live dashboard updates (+ optional event logging).
- **Batch (offline / export) pipeline**: video file upload → faster processing/export → **FFmpeg H.264 transcoding** → saved outputs + **Excel reports** + SQLite events.

It’s optimized for Intel CPUs with OpenVINO and is intended to run as one “appliance-like” process (plus external tools like FFmpeg).

##### Read the repo structure as architecture boundaries

- **`app.py`**: system entrypoint; Flask routes + orchestration between UI and pipelines.
- **`src/`**:
- `src/camera.py`: capture/stream handling, frame loop, likely live pipeline integration.
- `src/database.py`: SQLite event logging interface.
- **`config.py`**: global configuration (paths, toggles, thresholds, model paths).
- **`templates/` + `static/`**: web UI (HTML + JS + CSS).
- **`models/`**: model artifacts/config (`bytetrack.yaml`, exported OpenVINO model directory).
- **`scripts/`**:
- `export_model.py`: pulls YOLOv8n and exports to OpenVINO IR (build step).
- `draw_zones.py`: zone authoring tool that produces polygon definitions.
- **`data/`**:
- `data/office_*_zones.json`: the seat/zone geometry configs (core to “seat-locking” logic).
- `data/uploads/`: user-uploaded videos for batch mode.
- `data/outputs/`: processed videos/images.
- `data/reports/`: Excel outputs for HR reporting.
- `data/samples/employee_template.xlsx`: reporting template.
- **`run_system.bat`**: Windows automation (venv setup, dependency install, warmup, launch).

##### Client/UI layer
- **Browser**
- Loads `templates/index.html`
- Runs `static/js/script.js` for:
- starting/stopping live preview
- triggering batch upload/export
- polling results / rendering stats

##### Web/API serving layer
- **Waitress WSGI Server** (production runtime per README)
- Hosts the Flask app
- **Flask Application (`app.py`)**
- Route handlers:
- live preview endpoints
- batch upload endpoints
- results/report download endpoints
- Orchestration: calls into camera/inference/db modules

##### Core CV pipeline layer (backend internal “engine”)
- **Frame Acquisition (`src/camera.py`)**
- RTSP/USB camera feed or video file reader (OpenCV)
- **Pre/Post Processing**
- resize/normalize, bbox parsing, filtering (anti-merging rules from README)
- **Inference Engine**
- **YOLOv8 model executed via OpenVINO Runtime**
- “model warming / JIT” (not a file, but a real lifecycle step worth annotating)
- **Tracking**
- ByteTrack configuration (`models/bytetrack.yaml`)
- **Seat-Based Spatial Logic**
- loads polygons from `data/office_*_zones.json`
- anchor-point heuristic (25% bbox height) + `pointPolygonTest`
- maps tracked person → workstation seat (identity anchoring)

##### Storage layer
As separate stores (not one generic “DB”):
- **SQLite DB** (via `src/database.py`) for event logging
- **Filesystem stores**
- `data/uploads/` (inputs)
- `data/outputs/` (rendered video/results)
- `data/reports/` (Excel exports)

##### Batch export/transcoding/reporting layer
- **Batch Processor** (likely orchestrated by Flask route)
- consumes uploaded video
- produces processed video + event summaries
- **FFmpeg (external process dependency)**
- H.264 transcoding for browser playback
- **Excel Report Generator**
- uses Pandas + template `data/samples/employee_template.xlsx`

##### Configuration flows
- **Zone JSON → Seat Logic**: polygons loaded at startup or per-job
- **`config.py` → Flask/CV Engine/Batch**: thresholds, model paths, directories

##### Lifecycle / provisioning flows (often omitted, but this project benefits from it)
- **`run_system.bat` → venv/pip → launch waitress/flask**
- **`scripts/export_model.py` → models/**: produces runtime model artifacts

- **Edge deployment / single-node**: all components run on one machine (Intel CPU).
- **Dual-mode architecture**: *Live Preview* vs *Turbo Batch Export* (make them two distinct pipelines sharing the same CV core).
- **External tool boundary**: FFmpeg is not a Python module—show it as an external executable invoked by the backend.
- **Persistence split**: SQLite for events + filesystem for artifacts + Excel for human deliverables.

- User (HR/Manager)
- Browser UI
- External Dependencies: FFmpeg, (optional) Camera/RTSP source, Ultralytics model source (for export step)

- user uses browser
- browser interacts with VAA
- VAA reads camera stream / video uploads
- VAA calls FFmpeg
- (optional) export script pulls model weights from internet

Inside VAA:
- Web Server (Waitress + Flask)
- CV Engine (OpenVINO + OpenCV + tracker)
- Batch Export/Transcode
- SQLite DB
- File Stores (uploads/outputs/reports)
- Config/Zone definitions

Inside CV Engine:
- Frame Acquisition (`src/camera.py`)
- Pre/Post Processing
- OpenVINO Inference (YOLOv8)
- Tracking (ByteTrack config)
- Seat Logic (polygon test + anchor heuristic + anti-merging filters)
- Event Logger (`src/database.py`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram 1 — System Context (Level 1)
    %% =========================
    subgraph "Diagram 1 — System Context (C4 Level 1)"
        direction TB

        User["User (HR/Manager)"]:::external
        Browser["Browser UI"]:::frontend

        subgraph "Vision Activity Analytics System (Single-node Edge Appliance)"
            direction TB
            VAA["VAA System"]:::system
        end

        CameraSource["Camera/RTSP/USB Source"]:::external
        FFmpegExt["FFmpeg (External Executable)"]:::external
        UltralyticsSrc["Ultralytics Model Source (Internet)"]:::external
        RunBat["Provisioning & Launch (run_system.bat)"]:::ops
        ExportScript["Model Export Utility (scripts/export_model.py)"]:::ops

        User -->|"uses"| Browser
        Browser -->|"HTTP"| VAA
        VAA -->|"reads_stream"| CameraSource
        VAA -->|"process_invocation"| FFmpegExt
        RunBat -->|"launches"| VAA
        ExportScript -->|"downloads_weights"| UltralyticsSrc
        ExportScript -->|"writes_OpenVINO_IR"| VAA
    end

    %% =========================
    %% Diagram 2 — Container Diagram (Level 2)
    %% =========================
    subgraph "Diagram 2 — Container Diagram (C4 Level 2)"
        direction TB

        Browser2["Browser UI (templates + static)"]:::frontend

        subgraph "Web/API Serving Layer"
            direction TB
            Waitress["Waitress WSGI Server"]:::api
            FlaskApp["Flask Application (app.py)"]:::api
            Waitress -->|"WSGI"| FlaskApp
        end

        subgraph "Core CV Pipeline Layer (Shared)"
            direction TB
            CVEngine["CV Engine (OpenCV + OpenVINO + Tracking + Seat Logic)"]:::engine
        end

        subgraph "Dual-Mode Execution"
            direction TB

            subgraph "Live Mode (Streaming/Preview)"
                direction TB
                LiveCtl["Live Preview Controller"]:::engine
            end

            subgraph "Batch Mode (Offline/Export)"
                direction TB
                BatchProc["Batch Processor"]:::engine
                ExcelGen["Excel Report Generator (Pandas + Template)"]:::report
            end
        end

        subgraph "Persistence Split"
            direction TB
            SQLite[("SQLite DB (Events)")]:::db

            Uploads["Folder: Uploads (data/uploads/)"]:::store
            Outputs["Folder: Outputs (data/outputs/)"]:::store
            Reports["Folder: Reports (data/reports/)"]:::store
            ExcelTemplate["Document: Employee Template (XLSX)"]:::doc

            ZoneA["Zones JSON (Office A)"]:::config
            ZoneB["Zones JSON (Office B)"]:::config
            Config["Global Config (config.py)"]:::config
        end

        FFmpeg2["FFmpeg (External Executable)"]:::external

        %% UI interactions
        Browser2 -->|"HTTP: start_stop_live,upload_export,poll_stats"| Waitress

        %% Orchestration
        FlaskApp -->|"kicks_off_live"| LiveCtl
        FlaskApp -->|"kicks_off_batch_job"| BatchProc
        FlaskApp -->|"serves_live_preview + metrics_JSON"| Browser2
        FlaskApp -->|"serves_download_links (H.264 + XLSX)"| Browser2

        %% Live path
        LiveCtl -->|"streams_frames"| CVEngine
        CVEngine -->|"writes_events"| SQLite

        %% Batch path
        FlaskApp -->|"stores_upload"| Uploads
        Uploads -->|"reads_input_video"| BatchProc
        BatchProc -->|"per_frame_analysis"| CVEngine
        BatchProc -->|"writes_rendered_media"| Outputs
        BatchProc -->|"process_invocation (transcode_H.264)"| FFmpeg2
        FFmpeg2 -->|"writes_H.264"| Outputs

        BatchProc -->|"builds_summaries"| ExcelGen
        ExcelGen -->|"uses_template"| ExcelTemplate
        ExcelGen -->|"writes_XLSX"| Reports

        %% Config + zones
        Config -->|"thresholds,paths,toggles"| FlaskApp
        Config -->|"model_paths,perf_tuning"| CVEngine
        Config -->|"directories,export_settings"| BatchProc
        ZoneA -->|"JSON(polygons)"| CVEngine
        ZoneB -->|"JSON(polygons)"| CVEngine
    end

    %% =========================
    %% Diagram 3 — Component Diagram (Level 3, Core Engine)
    %% =========================
    subgraph "Diagram 3 — Core CV Engine Components (C4 Level 3)"
        direction TB

        subgraph "CV Engine (Internal Components)"
            direction TB

            FrameAcq["Frame Acquisition (src/camera.py)"]:::engine
            PrePost["Pre/Post Processing\n(resize/normalize,bbox_parse,filtering)"]:::engine
            Inference["OpenVINO Inference (YOLOv8)\n(model_warmup/JIT)"]:::engine
            Tracking["Tracking (ByteTrack)"]:::engine
            SeatLogic["Seat-Based Spatial Logic\n(anchor_25% + pointPolygonTest + seat_locking)\n(anti-merging rules)"]:::engine
            DBAdapter["Event Logger Adapter (src/database.py)"]:::engine

            ByteTrackCfg["ByteTrack Config (models/bytetrack.yaml)"]:::config
            ZonesA3["Zones JSON (Office A)"]:::config
            ZonesB3["Zones JSON (Office B)"]:::config
            Config3["Global Config (config.py)"]:::config
            SQLite3[("SQLite DB (Events)")]:::db

            FrameAcq -->|"frames"| PrePost
            PrePost -->|"tensors"| Inference
            Inference -->|"detections"| Tracking
            Tracking -->|"tracks(track_id,bbox)"| SeatLogic
            SeatLogic -->|"occupancy_events"| DBAdapter
            DBAdapter -->|"SQL_writes"| SQLite3

            ByteTrackCfg -->|"tracker_params"| Tracking
            ZonesA3 -->|"polygons_JSON"| SeatLogic
            ZonesB3 -->|"polygons_JSON"| SeatLogic
            Config3 -->|"thresholds,paths"| FrameAcq
            Config3 -->|"thresholds,paths"| PrePost
            Config3 -->|"model_path,device"| Inference
            Config3 -->|"policy_toggles"| SeatLogic
            Config3 -->|"db_path"| DBAdapter
        end

        Note1["Note: Dual-mode architecture shares the same CV Engine.\nKey domain innovation: identity anchored to seat polygons (not Re-ID embeddings)."]:::note
    end

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click FlaskApp "https://github.com/montero52/vision-activity-analytics/blob/main/app.py"
    click Waitress "https://github.com/montero52/vision-activity-analytics/blob/main/README.md"
    click Config "https://github.com/montero52/vision-activity-analytics/blob/main/config.py"
    click Config3 "https://github.com/montero52/vision-activity-analytics/blob/main/config.py"
    click Browser2 "https://github.com/montero52/vision-activity-analytics/blob/main/templates/index.html"
    click Browser2 "https://github.com/montero52/vision-activity-analytics/blob/main/static/js/script.js"
    click Browser2 "https://github.com/montero52/vision-activity-analytics/blob/main/static/css/style.css"
    click FrameAcq "https://github.com/montero52/vision-activity-analytics/blob/main/src/camera.py"
    click DBAdapter "https://github.com/montero52/vision-activity-analytics/blob/main/src/database.py"
    click ByteTrackCfg "https://github.com/montero52/vision-activity-analytics/blob/main/models/bytetrack.yaml"
    click ZoneA "https://github.com/montero52/vision-activity-analytics/blob/main/data/office_A_zones.json"
    click ZonesA3 "https://github.com/montero52/vision-activity-analytics/blob/main/data/office_A_zones.json"
    click ZoneB "https://github.com/montero52/vision-activity-analytics/blob/main/data/office_B_zones.json"
    click ZonesB3 "https://github.com/montero52/vision-activity-analytics/blob/main/data/office_B_zones.json"
    click Uploads "https://github.com/montero52/vision-activity-analytics/tree/main/data/uploads/"
    click Outputs "https://github.com/montero52/vision-activity-analytics/tree/main/data/outputs/"
    click Reports "https://github.com/montero52/vision-activity-analytics/tree/main/data/reports/"
    click ExcelTemplate "https://github.com/montero52/vision-activity-analytics/blob/main/data/samples/employee_template.xlsx"
    click ExportScript "https://github.com/montero52/vision-activity-analytics/blob/main/scripts/export_model.py"
    click RunBat "https://github.com/montero52/vision-activity-analytics/blob/main/run_system.bat"
    click VAA "https://github.com/montero52/vision-activity-analytics/blob/main/scripts/draw_zones.py"
    click SeatLogic "https://github.com/montero52/vision-activity-analytics/blob/main/scripts/draw_zones.py"

    %% =========================
    %% Styles
    %% =========================
    classDef frontend fill:#D6ECFF,stroke:#2B6CB0,stroke-width:1px,color:#0B2545;
    classDef api fill:#E6FFFA,stroke:#0F766E,stroke-width:1px,color:#064E3B;
    classDef engine fill:#F3E8FF,stroke:#6D28D9,stroke-width:1px,color:#2E1065;
    classDef db fill:#FFF1F2,stroke:#BE123C,stroke-width:1px,color:#881337;
    classDef store fill:#FFFBEB,stroke:#B45309,stroke-width:1px,color:#78350F;
    classDef doc fill:#ECFCCB,stroke:#3F6212,stroke-width:1px,color:#1A2E05;
    classDef report fill:#E9FFE5,stroke:#2F855A,stroke-width:1px,color:#14532D;
    classDef config fill:#F1F5F9,stroke:#475569,stroke-width:1px,color:#0F172A;
    classDef external fill:#FFFFFF,stroke:#64748B,stroke-width:1px,stroke-dasharray: 6 4,color:#0F172A;
    classDef ops fill:#FFE4E6,stroke:#9F1239,stroke-width:1px,color:#4C0519;
    classDef system fill:#DCFCE7,stroke:#166534,stroke-width:2px,color:#052E16;
    classDef note fill:#FFFFFF,stroke:#94A3B8,stroke-width:1px,stroke-dasharray: 2 2,color:#334155;
```
