# talsperre/lecturesummarizer architecture

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

- Interactive diagram: https://gitdiagram.com/talsperre/lecturesummarizer
- Repository: https://github.com/talsperre/lecturesummarizer

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Django (Python) that automatically summarizes lecture videos using AI (speech recognition), computer vision (shot detection), and NLP (summarization & tag generation). Users upload videos via a web UI; the system splits videos into shots, extracts audio, converts speech to text, summarizes each clip, generates tags, indexes results in a database, and presents summaries and search results back to the user.

##### File Structure Analysis
- Top-level:
- videoSummarizer/             ← Django project root
- requirements.txt             ← Python dependencies
- documents/                   ← design docs and presentation
- Under videoSummarizer/:
- manage.py                    ← Django CLI entry point
- videoSummarizer/             ← Django settings, URL routing, WSGI/ASGI
- summarize/                   ← Core Django app: models, views, templates, static assets, forms, URLs
- Modular AI/processing code (each with Interface + implementation + tests):
- shot_detection/
- audio_generation/
- speech_recognition/
- summarization/
- tag_generation/
- Media storage under videoSummarizer/media/: videos, audio clips, metadata CSVs.

##### README Insights
- MVT (Model-View-Template) design pattern
- SOLID, clean code, interfaces abstract external libraries (PySceneDetect, FFMPEG, Google Speech API, YAKE)
- MySQL backend (VideoSummarizer database)
- Unit tests for each module

##### Main Components
a. User Interface
- Web browser → Django “summarize” app (views + templates + static)
b. Application Server
- Django core (manage.py, settings, URLs, WSGI/ASGI)
- Shot Detection
- Audio Generation
- Speech Recognition
- Summarization
- Tag Generation
d. Data Storage
- File system (media/videos, media/audio, metadata CSVs)
- MySQL database (video, clip, transcript, summary, tags tables)
e. External Services & Libraries
- PySceneDetect
- FFMPEG
- Google Speech Recognition API
- YAKE (keyword extraction)

##### Relationships & Data Flow
1. User uploads video → saved to media/videos
2. Shot Detection reads raw video → outputs video clips + split_times CSV → saved under media/
3. Audio Generation reads each clip → uses FFMPEG → writes audio files under media/audio
4. Speech Recognition reads audio files → calls Google API → writes transcripts
5. Summarization & Tag Generation read transcripts → generate summaries and keywords → stored in DB
6. Django Views query DB + media files → render HTML pages for search, summaries, playback

##### Architectural Patterns & Principles
- MVT (Django) for web layer
- Interface + Implementation modules for each AI step (SOLID, Open/Closed)
- Single Responsibility per processing module
- Clear separation: Web layer vs. Processing pipeline vs. Storage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Zones
    subgraph "Frontend Layer" 
        direction TB
        UI["Web Browser"]:::frontend
        SummApp["Summarize App\n(views, templates, static)"]:::frontend
    end

    subgraph "Backend Layer" 
        direction TB
        Mgmt["manage.py"]:::backend
        Settings["settings.py"]:::backend
        URLs["urls.py"]:::backend
        WSGI["wsgi.py"]:::backend
        ASGI["asgi.py"]:::backend
    end

    subgraph "Processing Pipeline" 
        direction TB
        ShotDet["Shot Detection Service"]:::processing
        AudioGen["Audio Generation Service"]:::processing
        SpeechRec["Speech Recognition Service"]:::processing
        Summarizer["Summarization Service"]:::processing
        TagGen["Tag Generation Service"]:::processing
    end

    subgraph "Storage Layer"
        direction TB
        Videos["Media: Raw Videos"]:::storage
        AudioClips["Media: Audio Clips"]:::storage
        CSVs["Media: Shot Metadata CSVs"]:::storage
        DB[(MySQL Database)]:::storage
    end

    subgraph "External Services"
        direction TB
        PyScene["PySceneDetect"]:::external
        FFMPEG["FFMPEG"]:::external
        GoogleAPI["Google Speech API"]:::external
        YAKE["YAKE"]:::external
    end

    %% Data Flow
    UI -->|1 Upload| SummApp
    SummApp -->|"Invokes Django Core"| Mgmt
    Mgmt --> Settings
    Mgmt --> URLs
    URLs --> SummApp
    SummApp -->|2 Start Pipeline| ShotDet
    ShotDet -->|Outputs Clips + CSV| AudioGen
    AudioGen -->|Produces Audio| SpeechRec
    SpeechRec -->|Creates Transcripts| Summarizer
    Summarizer -->|Generates Summaries| TagGen
    TagGen -->|Produces Tags| DB
    TagGen -->|Produces Tags| CSVs

    %% Storage flow
    ShotDet --> Videos
    ShotDet --> CSVs
    AudioGen --> AudioClips
    SpeechRec --> DB
    Summarizer --> DB

    %% UI retrieval
    SummApp -->|Queries| DB
    SummApp -->|Fetches Media| Videos
    SummApp -->|Fetches Media| AudioClips

    %% External integrations
    ShotDet --> PyScene
    AudioGen --> FFMPEG
    SpeechRec --> GoogleAPI
    Summarizer --> YAKE
    TagGen --> YAKE

    %% Click Events
    click SummApp "https://github.com/talsperre/lecturesummarizer/tree/master/videoSummarizer/summarize/"
    click Mgmt "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/manage.py"
    click Settings "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/videoSummarizer/settings.py"
    click URLs "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/videoSummarizer/urls.py"
    click WSGI "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/videoSummarizer/wsgi.py"
    click ASGI "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/videoSummarizer/asgi.py"
    click ShotDet "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/shot_detection/ShotDetectionInterface.py"
    click ShotDet "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/shot_detection/SplitVideoInterface.py"
    click ShotDet "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/shot_detection/PySceneDetection.py"
    click ShotDet "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/shot_detection/SplitVideo.py"
    click AudioGen "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/audio_generation/AudioGeneration.py"
    click SpeechRec "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/speech_recognition/SpeechRecognitionInterface.py"
    click SpeechRec "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/speech_recognition/GoogleSpeechRecognition.py"
    click SpeechRec "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/speech_recognition/SpeechRecognitionConfig.py"
    click Summarizer "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/summarization/SummarizationInterface.py"
    click Summarizer "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/summarization/WordFrequencySummarization.py"
    click Summarizer "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/summarization/YakeSummarization.py"
    click TagGen "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/tag_generation/TagGenerationInterface.py"
    click TagGen "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/tag_generation/TagGenerationAlgorithmia.py"
    click TagGen "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/tag_generation/TagGenerationPMI.py"
    click TagGen "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/tag_generation/YakeSummarization.py"
    click Videos "https://github.com/talsperre/lecturesummarizer/tree/master/videoSummarizer/media/videos/"
    click AudioClips "https://github.com/talsperre/lecturesummarizer/tree/master/videoSummarizer/media/audio/"
    click CSVs "https://github.com/talsperre/lecturesummarizer/tree/master/videoSummarizer/media/video_metadata/"
    click DB "https://github.com/talsperre/lecturesummarizer/blob/master/videoSummarizer/videoSummarizer/VideoSummarizer.sql"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef backend fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef processing fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef storage fill:#f5f5f5,stroke:#616161,color:#424242;
    classDef external fill:#e1bee7,stroke:#6a1b9a,color:#6a1b9a;
```
