# muhammad-zeeshan-khan/speech-recognition-app architecture

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

- Interactive diagram: https://gitdiagram.com/muhammad-zeeshan-khan/speech-recognition-app
- Repository: https://github.com/muhammad-zeeshan-khan/speech-recognition-app

## Overview

##### Project type and purpose
- This is a standalone desktop GUI application (“Speech Recognition Application”) written in Python.
- Its primary function is to accept or record audio input, send it to AssemblyAI’s speech‐to‐text API, receive the transcript, then optionally generate subtitles, summaries, and play back audio with overlays in a Pygame‐based interface.

##### File structure
Top‐level layout:
- main.py – application entrypoint / orchestrator
- interface.py – GUI (view) built on pygame
- api_communication.py – external API client (AssemblyAI integration)
- transcription.py – logic for preparing audio and parsing transcripts
- summary.py – post‐processing logic (text summarization)
- subtitles.py – generates subtitle data for display
- audio_player.py – encapsulates audio playback in the GUI
- utils.py – shared helper functions (e.g., file I/O, data formatting)
- credits.py – static credits screen/content
- keys.txt – local storage of your AssemblyAI API key
- sra_flowchart.drawio – existing rough sketch of the flow

##### Extract insights from the README
- GUI built on Python (pygame v2.5.2)
- Uses AssemblyAI’s API for transcription
- API key must be placed in keys.txt
- Supports download, play, subtitle overlay, summary generation

##### Main components
A. User Interface Layer
- interface.py (main menu, recording/upload UI, subtitles overlay, credits)
- audio_player.py (playback controls)
B. Application Controller / Orchestrator
- main.py – initializes GUI, routes UI events to business modules
C. Business Logic Modules
- api_communication.py – sends/receives JSON to/from AssemblyAI REST endpoints
- transcription.py – preps raw audio, handles polling or webhooks for transcript
- summary.py – invokes text‐summarization routines (could be local or external)
- subtitles.py – builds time‐coded subtitle files (e.g., SRT)
D. Utilities
- utils.py – file management, config loading (reads keys.txt), logging
- credits.py – static data source for “About” section
E. External Service
- AssemblyAI REST API (external dependency)
F. Local Storage / Assets
- keys.txt (API key)

##### Relationships & data flow
1. User interacts with the UI (interface.py) →
2. main.py routes the action:
- Record or load audio file → passes path to transcription.py
- transcription.py calls api_communication.py → calls AssemblyAI API → returns transcript
- transcript forwarded to summary.py (optional) → generates summary
- transcript forwarded to subtitles.py → generates .srt data
- UI (interface.py) plus audio_player.py display and play audio with subtitles overlay
3. utils.py provides shared services (config, logging) throughout

##### Architectural patterns & design principles
- MVC-like separation:
- View: interface.py + audio_player.py
- Controller: main.py
- Model/Business Logic: transcription.py, summary.py, subtitles.py, api_communication.py
- Single‐process, event‐driven GUI
- Layered approach: UI → Orchestrator → Domain Modules → External Service

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        UI_Interface["interface.py"]:::ui
        UI_AudioPlayer["audio_player.py"]:::ui
    end

    %% Controller
    subgraph "Application Controller"
        direction TB
        Controller["main.py"]:::controller
    end

    %% Business Logic Modules
    subgraph "Business Logic Modules"
        direction TB
        API_Comm["api_communication.py"]:::business
        Transcription["transcription.py"]:::business
        Summary["summary.py"]:::business
        Subtitles["subtitles.py"]:::business
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Utils["utils.py"]:::utility
        Credits["credits.py"]:::utility
    end

    %% Local Storage / Assets
    subgraph "Local Storage / Assets"
        direction TB
        APIKey["keys.txt"]:::storage
        Assets["others/"]:::storage
    end

    %% External Service
    subgraph "External Service"
        direction TB
        AssemblyAI("AssemblyAI REST API"):::external
    end

    %% Connections
    UI_Interface -->|pygame events| Controller
    UI_AudioPlayer -->|pygame events| Controller

    Controller -->|record/upload audio| Transcription
    Transcription -->|prepare audio| API_Comm
    API_Comm -->|HTTP/HTTPS JSON| AssemblyAI
    AssemblyAI -->|JSON transcript| API_Comm
    API_Comm -->|transcript| Transcription

    Transcription -->|transcript| Summary
    Transcription -->|transcript| Subtitles

    Summary -->|summary text| UI_Interface
    Subtitles -->|subtitle data| UI_Interface
    UI_AudioPlayer -->|play audio| UI_Interface

    Controller -->|uses| Utils
    UI_Interface -->|uses| Utils
    Transcription -->|uses| Utils
    Summary -->|uses| Utils
    Subtitles -->|uses| Utils
    API_Comm -->|reads key| APIKey
    UI_Interface -->|loads assets| Assets
    Credits -->|uses| UI_Interface

    %% Click Events
    click UI_Interface "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/interface.py"
    click UI_AudioPlayer "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/audio_player.py"
    click Controller "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/main.py"
    click API_Comm "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/api_communication.py"
    click Transcription "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/transcription.py"
    click Summary "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/summary.py"
    click Subtitles "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/subtitles.py"
    click Utils "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/utils.py"
    click Credits "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/credits.py"
    click APIKey "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/blob/master/keys.txt"
    click Assets "https://github.com/muhammad-zeeshan-khan/speech-recognition-app/tree/master/others/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef controller fill:#E6F7E6,stroke:#28A745,stroke-width:1px
    classDef business fill:#E8F1D4,stroke:#6F9C0D,stroke-width:1px
    classDef utility fill:#FFF4CC,stroke:#DB9F00,stroke-width:1px
    classDef storage fill:#F0F0F0,stroke:#6C757D,stroke-width:1px
    classDef external fill:#FFE5D4,stroke:#D65A31,stroke-width:1px
```
