# adamixa/wathiq_video_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/adamixa/wathiq_video_analysis
- Repository: https://github.com/adamixa/wathiq_video_analysis

## Overview

##### Project type and purpose
- This is a video-analysis application (a modular “full-stack” capstone tool) with:
- A user-facing Streamlit front-end for upload, parameter selection, and report display
- A back-end pipeline of specialized Python modules that perform video and audio analysis
- No persistent database; intermediate data are stored on the file system (CSVs, WAVs, model weights)
- An external API (OpenAI) for text summarization and recommendations

##### File structure
- Top-level directories map one-to-one with analysis domains:
- AudioProcessing/ (notebooks & extracted_audio.wav)
- BodyLanguage/ (notebooks, coords.csv, model weights)
- EyeContact/, FaceEmotion/, HandMovement/ likewise
- PythonScripts/ contains the production code:
- streamlit_app.py (UI controller)
- AudioProcessor.py, BodyLanguageRecognizer.py, EmotionDetector.py, EyeContact.py, HandMovementDetector.py (processing modules)
- ObjectTracker.py (shared utility)
- main.py (CLI orchestration)
- Config and dependency files: requirements.txt, .streamlit/config.toml
- Models & data stores on disk: .pkl, .pt, .wav, .csv, Haarcascade XMLs

##### Extract key insights from README
- Core features: body language, hand movement, eye contact, emotion, stutter detection & transcription, OpenAI-powered summarization
- Usage pattern: user launches Streamlit → selects or uploads video → “Analyze” triggers all modules → report visualized in app

a. Main components
1. User & Streamlit UI (Front-end)
2. Orchestrator / Controller (streamlit_app.py or main.py)
3. Video Preprocessor (ffmpeg wrapper)
4. Visual Analysis Modules (each runs on video frames)
– BodyLanguageRecognizer
– HandMovementDetector
– EyeContactAnalyzer
– EmotionDetector (DeepFace + YOLO)
– ObjectTracker (shared)
5. Audio Analysis Module (AudioProcessor)
– Stutter detector
– Speech-to-text (whisper or similar)
– Summarization (OpenAI API)
6. Aggregator & Report Generator
7. File System (raw videos, intermediate CSV/WAV, model weights)
8. External Service: OpenAI API
b. Relationships & flows
- User → (upload/select video) → Streamlit UI
- UI → Orchestrator invokes Video Preprocessor → frame stream + extracted audio
- Frame stream → forked in parallel to each Visual Analysis Module → outputs CSV/metrics
- Extracted audio → AudioProcessor → stutter report + transcription
- Transcription → OpenAI API → text summary & recommendations
- All module outputs → Aggregator → final data structure
- Aggregator → Streamlit UI → display charts, videos, text report
c. Architectural patterns & design principles
- Modular pipeline: each analysis domain is a separate component in a data-flow graph
- Single-process “monolith” with clear separation of concerns (no microservices)
- Shared utility layer (ObjectTracker, ModelLoader) for DRY code
- Layered: UI layer → orchestration layer → processing layer → external layer
d. Key technologies & frameworks
- Python 3.x, Streamlit
- MediaPipe, OpenCV, Haarcascades
- Ultralytics YOLO (yolov8n.pt)
- DeepFace (emotion)
- ffmpeg (audio extraction)
- OpenAI API (summaries & recommendations)

##### Diagramming recommendations
[Streamlit UI], [Orchestrator], [BodyLanguageRecognizer], [AudioProcessor], [Aggregator]
(raw_videos), (extracted_audio.wav), (model_weights/*.pkl/.pt), (coords.csv)
- Use a cloud symbol or rounded rectangle for external service:
{OpenAI API}
User → UI → Orchestrator → {Video Preprocessor} → Visual Modules → Aggregator → UI
- Blue = UI / Orchestration
- Green = Processing Modules
- Yellow = Data Storage
- Purple = External Services

##### Detail and clarity
- Parallel flows for the five visual modules
- Final step of feeding the aggregated results back to the UI for rendering

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    User["User"]
    UI["Streamlit UI"]:::ui
    User -->|"interact/upload video"| UI

    %% Orchestration Layer
    Orches["Orchestrator"]:::orchestrator
    UI -->|"trigger analysis"| Orches

    %% Processing Layer
    VideoPrep["Video Preprocessor\n(ffmpeg wrapper)"]:::processing
    Orches -->|"invoke preprocessing"| VideoPrep

    %% Visual Analysis Subsystem
    subgraph "Visual Analysis Modules"
        Body["BodyLanguageRecognizer"]:::processing
        Hand["HandMovementDetector"]:::processing
        Eye["EyeContactAnalyzer"]:::processing
        Emo["EmotionDetector"]:::processing
        Shared["Object Tracker\n(Utility)"]:::processing
    end

    %% Audio Analysis Subsystem
    subgraph "Audio Analysis Module"
        AudioMod["AudioProcessor\n(Stutter, ASR, Summarization)"]:::processing
    end

    %% Aggregator & Reporting
    Aggregator["Aggregator & Report Generator"]:::orchestrator

    %% Data Storage Layer
    RawVid[(raw_videos)]:::storage
    ExtractedAudio[(extracted_audio.wav)]:::storage
    YOLO[(yolov8n.pt)]:::storage
    BodyModel[(body_language.pkl)]:::storage
    Haar[(haarcascade_frontalface_default.xml)]:::storage
    CSVHand[(hand_movement_data.csv)]:::storage
    Config[(config.toml)]:::storage
    Req[(requirements.txt)]:::storage
    Readme[(README.md)]:::storage
    VideosDir[(videos/)]:::storage

    %% External Services
    OpenAI{OpenAI API}:::external

    %% Data Flows
    RawVid -->|"video file"| VideoPrep
    VideoPrep -->|"extracted audio"| ExtractedAudio
    VideoPrep -->|"frames"| Body
    VideoPrep -->|"frames"| Hand
    VideoPrep -->|"frames"| Eye
    VideoPrep -->|"frames"| Emo
    VideoPrep -->|"audio.wav"| AudioMod

    BodyModel --> Body
    Shared --> Body
    Shared --> Hand
    Shared --> Eye
    Shared --> Emo
    YOLO --> Emo
    Haar --> Eye
    CSVHand --> Hand

    AudioMod -->|"transcript"| OpenAI
    OpenAI -->|"summary & recommendations"| AudioMod

    Body -->|"body_metrics.csv"| Aggregator
    Hand -->|"hand_metrics.csv"| Aggregator
    Eye -->|"eye_metrics.csv"| Aggregator
    Emo -->|"emotion_metrics.csv"| Aggregator
    AudioMod -->|"transcript & summary"| Aggregator

    Aggregator -->|"final report"| UI

    %% Click Events
    click UI "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/streamlit_app.py"
    click Orches "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/main.py"
    click VideoPrep "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/AudioProcessor.py"
    click AudioMod "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/AudioProcessor.py"
    click Body "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/BodyLanguageRecognizer.py"
    click Hand "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/HandMovementDetector.py"
    click Eye "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/Eyecontact.py"
    click Emo "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/EmotionDetector.py"
    click Shared "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/object_tracker.py"
    click YOLO "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/yolov8n.pt"
    click BodyModel "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/body_language.pkl"
    click ExtractedAudio "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/extracted_audio.wav"
    click Haar "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/haarcascade_frontalface_default.xml"
    click CSVHand "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/hand_movement_data.csv"
    click VideosDir "https://github.com/adamixa/wathiq_video_analysis/tree/main/PythonScripts/videos/"
    click Config "https://github.com/adamixa/wathiq_video_analysis/blob/main/PythonScripts/.streamlit/config.toml"
    click Req "https://github.com/adamixa/wathiq_video_analysis/blob/main/requirements.txt"
    click Readme "https://github.com/adamixa/wathiq_video_analysis/blob/main/README.md"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#42A5F5,color:#000
    classDef orchestrator fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef processing fill:#C8E6C9,stroke:#43A047,color:#000
    classDef storage fill:#FFF9C4,stroke:#FBC02D,color:#000
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#000
```
