# sriijk/crowdguard-ai architecture

> Architecture diagram of the GitHub repository sriijk/crowdguard-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sriijk/crowdguard-ai
- Repository: https://github.com/sriijk/crowdguard-ai

## Overview

##### Project Type and Purpose
- CrowdGuard AI is a **full-stack computer-vision application** (monolithic codebase) delivered via Streamlit (Web UI) with two deployment modes (local vs. cloud) plus a legacy CLI version.
- Purpose: real-time video ingestion → people detection via YOLOv8 → zone-based density analysis → alerting (visual + audio) → analytics + CSV exports.

##### File Structure
Top-level items:
- .devcontainer/             ← dev-container configuration (VS Code Remote)
- .streamlit/                ← Streamlit theming & secrets
- app.py                     ← OpenCV-only CLI prototype
- app_local.py               ← Full-feature Streamlit app (webcam, TTS)
- app_cloud.py               ← Streamlit cloud version (upload + beep)
- utils.py                   ← Core logic (YOLO inference, grid split, logging)
- Beep2.m4a                  ← Audio asset for alerts
- requirements.txt, runtime.txt, packages.txt
- README.md, LICENSE

##### Extract Key Insights from README
- Three “frontends”: CLI (app.py), local UI (app_local.py), cloud UI (app_cloud.py)
- Core detection model: yolov8n.pt (external artifact)
- Data flows: video frames → YOLOv8 → counts per 3×3 zones → threshold check → UI alert + sound → metrics & heatmaps → CSV logs

##### Main Components to Model
A. User Interface Layer
1. Streamlit Frontend
– app_local.py (webcam + TTS via pyttsx3)
– app_cloud.py (file upload + M4A beep)
2. CLI Frontend: app.py (OpenCV window + console logs)
B. Video & Audio I/O
– Webcam or File Upload → Frame Stream
– Audio TTS/beep engine
C. Inference & Processing
– utils.py
- YOLOv8 Inference (ultralytics)
- Grid-based zone splitter (3×3)
- Density thresholding
D. Data Storage
– In-memory DataFrame (pandas)
– CSV Export (persistent log)
E. Analytics & Visualization
– Matplotlib/Seaborn for trend-charts & heatmaps
– Streamlit plots
F. External Artifacts & Config
– yolov8n.pt (model file)
– Beep2.m4a
– .streamlit config
– .devcontainer

##### Relationships & Data Flow
1. User triggers “Start” in Streamlit UI → invokes video source (webcam or upload).
4. If overcrowded → UI warning component + pyttsx3 or beep audio call.
5. Append timestamped counts to pandas.DataFrame → render trend chart + heatmap.
6. On demand → write DataFrame → CSV export.

##### Architectural Patterns & Design Principles
- **Layered Architecture**:
- Presentation (Streamlit, CLI)
- Application/Domain (utils.py: detection & analysis)
- Data (in-memory & CSV)
- **Modularization**: Separation of UI variants (local vs. cloud vs. CLI)
- **Single Responsibility**: utils.py handles only inference + grid logic
- **Extensibility**: Can swap in a new YOLO model or change grid size

a. Separate **Docker/DevContainer** layer for local dev and CI/CD.
b. **model download step** as a manual external dependency.
c. An optional **Cloud Storage** block for log archival (e.g., S3).
e. **.streamlit** config feeding the frontend at runtime.

##### Putting It All Together

┌──────────────────────────┐
│         User UI          │
│ ┌────────────┐ ┌───────┐ │
│ │app_local.py│ │app_   │ │
│ │(Streamlit) │ │cloud  │ │
│ └────────────┘ └───────┘ │
└──────────┬─────────┬─────┘
│         │
▼         ▼
┌──────────────────────────┐
│   Inference & Processing │
│ ┌──────────────┐         │
│ │YOLOv8 Engine │         │
│ └──────────────┘         │
│ ┌──────────────┐         │
│ │ Grid Logic   │         │
│ └──────────────┘         │
└──────────┬───────────────┘
│
▼
┌──────────────────────────┐
│   Alerting Services      │
│ ┌───────┐ ┌───────────┐  │
│ │TTS    │ │Beep Sound │  │
│ └───────┘ └───────────┘  │
└──────────┬───────────────┘
│
▼
┌──────────────────────────┐
│   Analytics & Storage    │
│ ┌───────────┐ ┌───────┐  │
│ │Trend Chart│ │ CSV   │  │
│ └───────────┘ └───────┘  │
└──────────┬───────────────┘
│
▼
External Artifacts
(.pt model, .m4a, .streamlit)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Local and Cloud Environments
    subgraph "Local Development Environment"
        DC[".devcontainer/devcontainer.json"]:::external
    end
    subgraph "Cloud Deployment Environment"
        SC["requirements.txt, packages.txt, runtime.txt"]:::external
    end

    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI Frontend\n(app.py)"]:::frontend
        LocalUI["Streamlit Frontend\nLocal UI\n(app_local.py)"]:::frontend
        CloudUI["Streamlit Frontend\nCloud UI\n(app_cloud.py)"]:::frontend
    end

    %% Inference & Processing Layer
    subgraph "Inference & Processing" 
        Utils["Core Logic\n(utils.py)"]:::compute
        YOLO["YOLOv8 Engine"]:::compute
        Grid["Grid Logic\n(3×3 zones)"]:::compute
        Threshold["Density Threshold Logic"]:::compute
    end

    %% Alerting Services Layer
    subgraph "Alerting Services"
        TTS["pyttsx3 TTS Engine"]:::alert
        Beep["Beep Sound Player"]:::alert
    end

    %% Analytics & Storage Layer
    subgraph "Analytics & Storage"
        DF["In-memory DataFrame\n(pandas)"]:::storage
        Trend["Trend Chart & Heatmap"]:::storage
        CSV["CSV Export\n(persistent log)"]:::storage
        S3["Cloud Storage\n(e.g., S3)"]:::storage
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Model["yolov8n.pt"]:::external
        BeepAsset["Beep2.m4a"]:::external
        StreamlitConfig[".streamlit/packages.txt"]:::external
        Docs["README.md & LICENSE"]:::external
    end

    %% Data Flows & Relationships
    CLI -->|"FrameStream"| Utils
    LocalUI -->|"FrameStream"| Utils
    CloudUI -->|"UploadedVideo"| Utils

    Utils -->|"infer()"| YOLO
    YOLO -->|"BoundingBoxes"| Utils
    Utils -->|"zones()"| Grid
    Grid -->|"Counts"| Threshold

    Threshold -->|Overcrowd?| TTS
    Threshold -->|Overcrowd?| Beep

    Utils -->|"append Row"| DF
    DF -->|"render"| Trend
    LocalUI -->|"display"| Trend
    CloudUI -->|"display"| Trend

    LocalUI -->|"export"| CSV
    CloudUI -->|"export"| CSV
    CSV -->|"archive"| S3

    StreamlitConfig --> LocalUI
    StreamlitConfig --> CloudUI

    DC --> LocalUI
    DC --> Utils

    SC --> CloudUI
    SC --> Utils

    Model --> YOLO
    BeepAsset --> Beep
    Docs --> CLI
    Docs --> LocalUI
    Docs --> CloudUI
    Docs --> Utils

    %% Click Events
    click CLI "https://github.com/sriijk/crowdguard-ai/blob/main/app.py"
    click LocalUI "https://github.com/sriijk/crowdguard-ai/blob/main/app_local.py"
    click CloudUI "https://github.com/sriijk/crowdguard-ai/blob/main/app_cloud.py"
    click Utils "https://github.com/sriijk/crowdguard-ai/blob/main/utils.py"
    click BeepAsset "https://github.com/sriijk/crowdguard-ai/blob/main/Beep2.m4a"
    click DC "https://github.com/sriijk/crowdguard-ai/blob/main/.devcontainer/devcontainer.json"
    click StreamlitConfig "https://github.com/sriijk/crowdguard-ai/blob/main/.streamlit/packages.txt"
    click SC "https://github.com/sriijk/crowdguard-ai/blob/main/requirements.txt"
    click SC "https://github.com/sriijk/crowdguard-ai/blob/main/packages.txt"
    click SC "https://github.com/sriijk/crowdguard-ai/blob/main/runtime.txt"
    click Docs "https://github.com/sriijk/crowdguard-ai/blob/main/README.md"
    click Docs "https://github.com/sriijk/crowdguard-ai/tree/main/LICENSE"

    %% Styles
    classDef frontend fill:#FFA500,stroke:#333,stroke-width:1px
    classDef compute fill:#1E90FF,stroke:#333,stroke-width:1px
    classDef storage fill:#32CD32,stroke:#333,stroke-width:1px
    classDef alert fill:#FF4500,stroke:#333,stroke-width:1px
    classDef external fill:#A9A9A9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
