# us107/capstone-project-25 architecture

> Architecture diagram of the GitHub repository us107/capstone-project-25, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/us107/capstone-project-25
- Repository: https://github.com/us107/capstone-project-25

## Overview

##### Project type and purpose
- This is a full-stack, AI-powered video surveillance system. It ingests live or recorded video, processes it with computer-vision and deep-learning models, stores activity logs and relationships, and exposes results via interactive dashboards and reports.

##### File structure
- Top-level Python scripts each implement one stage of the pipeline:
- csvfiles_storage.py / newcloudcsvstorage.py – local and cloud CSV storage modules
- dashboardneo.py / realtime_dashboardneo.py / realtimeclouddashboard.py – Streamlit frontends for local and cloud dashboards backed by Neo4j
- extracted_frames.py – frame-extraction (FFmpeg/OpenCV)
- deepsort_yolo.py – object detection (YOLOv8) + tracking (DeepSORT)
- r3d_18activity.py – spatiotemporal action recognition (3D ResNet-18)
- generate_alerts.py – classify and emit real-time alerts
- generate_summary.py – compile summaries, invoke Groq LLM for PDF reports
- data_splitting.py – training/validation data prep
- testing.py – unit/integration tests
- requirements.txt and README.md document dependencies and high-level architecture.

##### README for additional insights
- Confirms real-time anomaly detection, centralized storage, interactive Streamlit dashboards, Neo4j for event-relationship graph, and Groq LLM for report generation.

##### Main components and their interactions
a. Video Ingestion
- sources: CCTV streams or video files
- script: extracted_frames.py
b. Object Tracking
- deepsort_yolo.py uses YOLOv8 + DeepSORT
c. Action Recognition
- r3d_18activity.py (3D ResNet-18)
d. Anomaly & Alert Generation
- generate_alerts.py
e. Summary & Report Generation
- generate_summary.py → Groq LLM
f. Storage
- csvfiles_storage.py (local CSV)
- newcloudcsvstorage.py (cloud CSV)
- Neo4j (graph storage of event relationships)
g. Dashboards / UI
- dashboardneo.py (local Streamlit + Neo4j)
- realtime_dashboardneo.py / realtimeclouddashboard.py for live updates

##### Architectural patterns & design principles
- Modular data-processing pipeline: each script is a standalone stage.
- Event-driven triggers or scheduler to chain scripts.
- Separation of concerns: compute modules vs. storage modules vs. UI modules.
- Extensibility hooks (e.g., Whisper for audio, edge deployment).

##### Technologies, frameworks, libraries
- Python ecosystem: OpenCV, FFmpeg, PyTorch
- Detection & tracking: YOLOv8, DeepSORT
- Recognition: 3D ResNet-18
- Dashboard: Streamlit
- Graph DB: Neo4j
- LLM: Groq (PDF report generation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingestion & Preprocessing
    subgraph "Ingestion & Preprocessing"
        direction TB
        EF["Frame Extraction\n(extracted_frames.py)"]:::compute
    end

    %% ML Compute Layer
    subgraph "ML Compute"
        direction TB
        OD["Object Detection & Tracking\n(deepsort_yolo.py)"]:::compute
        AR["Action Recognition\n(r3d_18activity.py)"]:::compute
        AG["Anomaly & Alert Generation\n(generate_alerts.py)"]:::compute
        SG["Summary & Report Generation\n(generate_summary.py)"]:::compute
    end

    %% Storage Layer
    subgraph "Storage & Database"
        direction TB
        CSV_LOCAL["Local CSV Storage\n(csvfiles_storage.py)"]:::storage
        CSV_CLOUD["Cloud CSV Storage\n(newcloudcsvstorage.py)"]:::external
        NEO["Neo4j Graph DB"]:::storage
    end

    %% UI Layer
    subgraph "User Interface"
        direction TB
        DASH_LOCAL["Local Dashboard\n(dashboardneo.py)"]:::ui
        DASH_RT_LOCAL["Real-Time Local Dashboard\n(realtime_dashboardneo.py)"]:::ui
        DASH_RT_CLOUD["Real-Time Cloud Dashboard\n(realtimeclouddashboard.py)"]:::ui
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        DS["Data Prep\n(data_splitting.py)"]:::compute
        TEST["Testing\n(testing.py)"]:::compute
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["Groq LLM\n(PDF Reports)"]:::external
    end

    %% Data Flow
    EF -->|frames via filesystem| OD
    OD -->|detections JSON| AR
    AR -->|features| AG
    AG -->|alerts JSON| CSV_LOCAL
    AG -->|alerts JSON| CSV_CLOUD
    AG -->|graph events| NEO
    AG -->|real-time alerts| DASH_RT_LOCAL
    AG -->|real-time alerts| DASH_RT_CLOUD
    SG -->|PDF report| LLM
    SG -->|summary CSV| CSV_LOCAL
    SG -->|summary CSV| CSV_CLOUD
    SG -->|event relationships| NEO
    CSV_LOCAL -->|CSV read| DASH_LOCAL
    NEO -->|Cypher queries| DASH_LOCAL
    NEO -->|real-time stream| DASH_RT_LOCAL
    NEO -->|real-time stream| DASH_RT_CLOUD

    %% Click Events
    click EF "https://github.com/us107/capstone-project-25/blob/main/extracted_frames.py"
    click OD "https://github.com/us107/capstone-project-25/blob/main/deepsort_yolo.py"
    click AR "https://github.com/us107/capstone-project-25/blob/main/r3d_18activity.py"
    click AG "https://github.com/us107/capstone-project-25/blob/main/generate_alerts.py"
    click SG "https://github.com/us107/capstone-project-25/blob/main/generate_summary.py"
    click CSV_LOCAL "https://github.com/us107/capstone-project-25/blob/main/csvfiles_storage.py"
    click CSV_CLOUD "https://github.com/us107/capstone-project-25/blob/main/newcloudcsvstorage.py"
    click DASH_LOCAL "https://github.com/us107/capstone-project-25/blob/main/dashboardneo.py"
    click DASH_RT_LOCAL "https://github.com/us107/capstone-project-25/blob/main/realtime_dashboardneo.py"
    click DASH_RT_CLOUD "https://github.com/us107/capstone-project-25/blob/main/realtimeclouddashboard.py"
    click DS "https://github.com/us107/capstone-project-25/blob/main/data_splitting.py"
    click TEST "https://github.com/us107/capstone-project-25/blob/main/testing.py"

    %% Styles
    classDef compute fill:#D0E6FF,stroke:#0A66C2,color:#0A66C2
    classDef storage fill:#D6F5D6,stroke:#28A028,color:#28A028
    classDef ui fill:#FFE6CC,stroke:#E65C00,color:#E65C00
    classDef external fill:#E8D0FF,stroke:#7A00E6,color:#7A00E6
```
