# maycods/real-time-violence-detection-system architecture

> Architecture diagram of the GitHub repository maycods/real-time-violence-detection-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maycods/real-time-violence-detection-system
- Repository: https://github.com/maycods/real-time-violence-detection-system

## Overview

##### Project Type and Purpose
- This project is a deep learning–based real-time violence detection system designed to monitor surveillance videos. It automatically processes video streams, detects violent actions using a trained CNN model, and then triggers alerts (e.g., alarms and screenshot captures) in addition to providing a user interface for live monitoring. It also includes a separate feature for keyframe extraction (video summarization).
- The README clarifies that the detection component was trained on specific datasets and that the project demonstrates a full system intended for real-world surveillance applications.

##### Analysis of File Structure
- Key Files:
- Interface.ipynb – likely serves as the main user interface, built in Jupyter Notebook, to display camera feeds, trigger detection, and handle user interactions.
- cnn_final_final.keras – holds the pre-trained CNN model used for violence detection.
- requirements.txt – lists Python dependencies and frameworks (likely including deep learning libraries).
- alarms/medical_alarm.mp3 – the audio file used to sound a real-time alarm when violence is detected.
- DEMO/ – includes sample videos (for demo or testing) to validate the system functionality.
- screenshots/ – designated folder to store images captured when violent activity is detected.
- The simplicity of the structure (a mix of demonstration media, the trained model, and interface code) implies the architecture is self-contained without a heavy backend/frontend separation. However, it still conceptually divides into multiple logical components.

a. Main Components:
- Video Input Source: Represents real-time camera feeds (or pre-recorded video input from the DEMO directory for demonstration/testing).
- Preprocessing/Keyframe Extraction Module: Handles video stream processing, keyframe extraction, and any preprocessing required before detection.
- Violence Detection Module: Uses the CNN model (loaded from cnn_final_final.keras). This is where deep-learning inference occurs.
- Alarm & Alert Mechanism: Connected to the detection module. On violent activity detection, it triggers an audible alarm (via the MP3 in the alarms folder) and commands the saving of a screenshot (in the screenshots directory).
- User Interface Module: Implemented in Interface.ipynb, providing a dashboard for live video streams, displaying detection status, managing camera zoom, and interfacing keyframe extraction features.
- Optional: A separate component for video summarization functions provided by the keyframe extraction feature.

b. Relationships and Interactions:
- The Video Input Source feeds directly into the Preprocessing/Keyframe Extraction Module.
- Preprocessed frames (or keyframes) are then passed to the Violence Detection Module where the CNN infers if violence is occurring.
- All results, including live video and detection outputs, are displayed or updated in the User Interface.
- Optionally, user actions from the UI (like uploading a video for keyframe extraction) route back to the Preprocessing/Keyframe Extraction Module.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: Distinguish between data ingestion (video input), processing (preprocessing and detection), alerting (alarm/screenshot), and user interaction (interface).
- Real-time Data Flow: Emphasize the pipeline nature where video streams are continuously analyzed.
- Modularity: Each component (detection, alerting, UI) is logically isolated even if they are implemented within a single application.
- Extensibility: The interface’s tabbed design indicates planned scalability, e.g. adding more processing features or extended monitoring functions.

d. Relevant Technologies, Frameworks, or Libraries:
- Deep Learning: Keras is used for the CNN, indicated by the .keras file.
- Python: Evident from the .ipynb notebook and requirements.txt.
- Multimedia Processing: Likely using libraries (such as OpenCV) for video stream handling.
- UI Development: Managed through a Jupyter Notebook interface.
- File Management: Local file system folders (ALARMS, screenshots, DEMO videos) for storing media and triggered events.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    VI["Video Input Source"]:::input
    PP["Preprocessing/Keyframe Extraction Module"]:::input
    VD["Violence Detection (CNN)"]:::detection
    UI["User Interface (Jupyter Notebook)"]:::ui

    %% Alarm & Alert Mechanism subgraph
    subgraph "Alarm & Alert Mechanism"
        AS["Alarm Sound"]:::alarm
        SC["Screenshot Capture"]:::alarm
    end

    %% Connections
    VI -->|"video_stream"| PP
    PP -->|"processed_frame"| VD
    VD -->|"detection_result"| AS
    VD -->|"detection_result"| SC
    VD -->|"detection_result"| UI
    AS -->|"alert_trigger"| UI
    UI -->|"keyframe_extraction_request"| PP

    %% Click Events
    click VI "https://github.com/maycods/real-time-violence-detection-system/tree/main/DEMO"
    click VD "https://github.com/maycods/real-time-violence-detection-system/blob/main/cnn_final_final.keras"
    click AS "https://github.com/maycods/real-time-violence-detection-system/blob/main/alarms/medical_alarm.mp3"
    click SC "https://github.com/maycods/real-time-violence-detection-system/tree/main/screenshots"
    click UI "https://github.com/maycods/real-time-violence-detection-system/blob/main/Interface.ipynb"

    %% Styles
    classDef input fill:#b3d9ff,stroke:#000,stroke-width:2px;
    classDef detection fill:#c1e1c5,stroke:#000,stroke-width:2px;
    classDef alarm fill:#f4cccc,stroke:#000,stroke-width:2px;
    classDef ui fill:#fff2cc,stroke:#000,stroke-width:2px;
```
