# zohaibkhan101/cammind architecture

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

- Interactive diagram: https://gitdiagram.com/zohaibkhan101/cammind
- Repository: https://github.com/zohaibkhan101/cammind

## Overview

##### Project Type and Purpose
- CamMind is a local, Python-based AI CCTV surveillance system with a minimal web UI.
- It captures a real-time video feed (webcam or IP camera), sends frames through a pretrained vision-language model (BLIP), overlays captions, applies judgment logic, logs events, and displays results in a browser.

##### File Structure
- Top-Level Files
- app.py            → Flask application entrypoint and HTTP routing
- cctv_ai.py        → Core video capture, ML inference, overlay & judgment logic
- requirements.txt  → Python dependencies (Torch, Transformers, OpenCV, Flask)
- activity_log.txt  → Plain-text log of alerts and events
- README.md         → Project documentation
- templates/        → HTML templates (index.html) for the web UI
- No separate “frontend” folder – the single-page UI is served by Flask’s templates.
- No external microservices; everything runs locally.

##### README for Technical Stack and Flow
- Dependencies: Python 3.7+, OpenCV, PyTorch, Transformers.
- Runtime: “python aicctv.py” or “python app.py” (web UI).
- Judgement logic inside cctv_ai.py is customizable.
- Optional directories (snapshots/, logs/) for future persistence.

##### Main Components & Their Relationships
a. External Camera Source
– Webcam or IP camera
– Delivers raw video frames to the system
b. Flask Web Server (app.py)
– Serves index.html at “/”
– Exposes endpoints (e.g., “/start”, “/stop”) or WebSocket for frame streaming
c. Video Processing Module (cctv_ai.py)
– Reads frames from camera via OpenCV
– Feeds each frame to the BLIP model for captioning
– Applies “judgement logic” (e.g., suspicious activity rules)
d. ML Inference Engine (Vision-Language Model)
– BLIP model loaded via Hugging Face Transformers and Torch
– Returns text description for each frame
e. Overlay & Display
– Draws caption text on frame
– Streams annotated frames back to the browser
f. Logging & Storage
– Writes timestamped events to activity_log.txt (and optionally snapshots/)
– Could expand to SQLite or CSV in future

##### Architectural Patterns and Design Principles
- MVC-style separation:
- Model = BLIP model + judgment rules
- View  = HTML template + overlaid video feed
- Controller = Flask routes + cctv_ai orchestrator
- Modular pipeline: capture → inference → logic → overlay → display → log
- Single deployable service (no external microservices)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interfaces
    subgraph "External Interfaces"
        Camera["External Camera Source"]:::external
        Browser["Web Browser (index.html)"]:::external
    end

    %% Backend Services
    subgraph "Backend"
        Flask["Flask Web Server (app.py)"]:::backend
        Processing["Video Processing Module (cctv_ai.py)"]:::backend
        ML["ML Inference Engine (BLIP Model)"]:::ml
        Overlay["Overlay & Display"]:::backend
        Logging["Logging & Storage"]:::storage
    end

    %% Documentation and Dependencies
    subgraph "Project Files"
        Requirements["requirements.txt"]:::storage
        Readme["README.md"]:::storage
    end

    %% Data Flows
    Camera -->|"raw frames"| Processing
    Browser -->|"HTTP/WebSocket"| Flask
    Flask -->|"dispatch start/stop"| Processing
    Processing -->|"frame for inference"| ML
    ML -->|"caption text"| Processing
    Processing -->|"annotated frames"| Overlay
    Overlay -->|"stream frames"| Browser
    Processing -->|"events"| Logging

    %% File references via click events
    click Camera "https://github.com/zohaibkhan101/cammind/blob/main/cctv_ai.py"
    click Flask "https://github.com/zohaibkhan101/cammind/blob/main/app.py"
    click Browser "https://github.com/zohaibkhan101/cammind/blob/main/templates/index.html"
    click Processing "https://github.com/zohaibkhan101/cammind/blob/main/cctv_ai.py"
    click ML "https://github.com/zohaibkhan101/cammind/blob/main/cctv_ai.py"
    click Overlay "https://github.com/zohaibkhan101/cammind/blob/main/cctv_ai.py"
    click Overlay "https://github.com/zohaibkhan101/cammind/blob/main/templates/index.html"
    click Logging "https://github.com/zohaibkhan101/cammind/blob/main/activity_log.txt"
    click Logging "https://github.com/zohaibkhan101/cammind/blob/main/cctv_ai.py"
    click Requirements "https://github.com/zohaibkhan101/cammind/blob/main/requirements.txt"
    click Readme "https://github.com/zohaibkhan101/cammind/blob/main/README.md"

    %% Styling
    classDef external fill:#c6f6d5,stroke:#2f855a,color:#22543d;
    classDef backend fill:#bee3f8,stroke:#2b6cb0,color:#2c5282;
    classDef ml fill:#fbd38d,stroke:#dd6b20,color:#975a16;
    classDef storage fill:#e2e8f0,stroke:#4a5568,color:#2d3748;
```
