How sriijk/crowdguard-ai works
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)