# chidiwilliams/buzz architecture

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

- Interactive diagram: https://gitdiagram.com/chidiwilliams/buzz
- Repository: https://github.com/chidiwilliams/buzz

## Overview

##### Main Components
- User Interface (GUI): All the “widgets” (found under buzz/widgets, buzz/widgets/transcriber, buzz/widgets/preferences_dialog, etc.). This component is responsible for presenting the main window, dialogs, toolbars, and handling user input (drag-and-drop file import, transcript viewing/edits, and live-recording controls).
- Transcription Engine: Located in buzz/transcriber (and related modules such as buzz/transcriber/whisper_cpp, file_transcriber, etc.), this component processes the audio input. It calls Whisper (or utilizes a local model) for generating transcriptions and may handle different modes such as file-based or live recording.
- Database & Caching: The buzz/db directory holds code to manage the local database, DAO (Data Access Objects) for different transcription entities and segments, and services (e.g., transcription_service) that wrap DB operations and enable caching or persistence of transcription data.
- Command Line Interface (CLI) and Application Entry: The buzz/cli.py and buzz/__main__.py are responsible for handling command-line interactions and application startup. They act as the glue between the UI, transcription engine, and backend.

##### Relationships and Data Flow
- Data Flow from Input to Output:
– The UI component captures user actions (drop a file, start live recording, adjust preferences).
– The transcriber engine then processes the audio data (invoking file_transcriber, recording_transcriber, or Whisper implementations) and sends transcription text to the database layer.
– The DB operations (using DAO patterns) persist transcripts so that they can be retrieved, edited, and displayed back in the UI.
- Configuration and Localization:
– The settings module feeds application configuration (like transcriber modes, shortcut settings) to both the GUI and backend.
– A localization module makes sure that translations (files under buzz/locale) are used to display content in multiple languages.
- External Dependencies:
– There is integration with OpenAI Whisper as the underlying transcription service.
– GPU support might be enabled via PyTorch and associated CUDA libraries, which is configured externally.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Notice how the project splits the responsibilities into distinct modules (UI, transcription, persistence, settings, and localization).
- Modularization and Layering: The project design follows a layered architecture where the presentation (widgets), application logic (transcriber, CLI), and data storage (db, caching) are separated.
- Extensibility: Modules for translation, different transcriber implementations (e.g., whisper_cpp vs. OpenAI APIs), and configurable preferences make it easier to extend functionality.

##### Technologies, Frameworks, and Libraries to Highlight
- Python is the main development language.
- OpenAI Whisper and its variants (including wrappers for whisper_cpp) are critical for audio processing.
- GUI framework (likely PyQt, TKinter, or another similar framework—check buzz/widgets naming conventions) handles the application UI.
- Database interactions using either SQLite (given the local file-based schema in buzz/schema.sql) or a similar embedded database.
- Testing is comprehensive (using pytest) as seen in the tests directory.
- Packaging and continuous integration infrastructure (Makefile, GitHub workflows, snapcraft, flatpak configurations) which ensure build and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["Main Window (buzz/widgets)"]:::ui
        UI2["Preferences Dialog (buzz/widgets/preferences_dialog)"]:::ui
        UI3["Transcriber Widget (buzz/widgets/transcriber)"]:::ui
        UI4["Transcript Viewer (buzz/widgets/transcription_viewer)"]:::ui
    end

    %% Transcription Engine Layer
    subgraph "Transcription Engine"
        T1["File Transcriber (buzz/transcriber/file_transcriber.py)"]:::transcription
        T2["Recording Transcriber (buzz/transcriber/recording_transcriber.py)"]:::transcription
        T3["Whisper C++ (buzz/transcriber/whisper_cpp.py)"]:::transcription
        T4["Whisper File Transcriber (buzz/transcriber/whisper_file_transcriber.py)"]:::transcription
        T5["OpenAI Whisper API File Transcriber (buzz/transcriber/openai_whisper_api_file_transcriber.py)"]:::transcription
    end

    %% Data Persistence Layer
    subgraph "Data Persistence Layer"
        D1["Database Service (buzz/db/db.py)"]:::db
        D2["DAO & Entities (buzz/db)"]:::db
        D3["Migrator & Cache (buzz/db/migrator.py, buzz/db/cache.py)"]:::db
    end

    %% Asset Management & Settings
    subgraph "Configuration & Assets"
        S1["Static Assets (buzz/assets)"]:::settings
        S2["Localization (buzz/locale)"]:::settings
        S3["Application Settings (buzz/settings)"]:::settings
        S4["User Settings (buzz/store/keyring_store.py)"]:::settings
    end

    %% CLI & Application Entry
    subgraph "CLI & Application Entry"
        C1["CLI (buzz/cli.py)"]:::cli
        C2["App Entry (buzz/__main__.py)"]:::cli
    end

    %% Data Flow Connections
    %% UI to Transcription Engine
    UI1 -->|"captures_input"| T1
    UI1 -->|"captures_input"| T2
    UI3 -->|"triggers_transcription"| T1
    UI3 -->|"triggers_transcription"| T2
    UI4 -->|"displays_transcript"| D1

    %% Transcription Engine to Database
    T1 -->|"stores_transcript"| D1
    T2 -->|"stores_transcript"| D1
    T3 -->|"supports_transcription"| T1
    T4 -->|"alternative_file_transcription"| T1
    T5 -->|"alternative_API_transcription"| T1

    %% Database Back to UI for display and editing
    D1 -->|"retrieves_transcript"| UI4
    D2 --> D1
    D3 --> D1

    %% Configuration Dependencies
    S3 -->|"configures"| UI1
    S3 -->|"configures"| T1
    S2 -->|"localizes"| UI1
    S2 -->|"localizes"| UI4

    %% CLI & App Entry triggers
    C1 -->|"starts_app"| UI1
    C1 -->|"initiates_transcription"| T1
    C2 -->|"launches_app"| UI1
    C2 -->|"launches_app"| T1

    %% Click Events
    click UI1 "https://github.com/chidiwilliams/buzz/tree/main/buzz/widgets"
    click UI2 "https://github.com/chidiwilliams/buzz/tree/main/buzz/widgets/preferences_dialog"
    click UI3 "https://github.com/chidiwilliams/buzz/tree/main/buzz/widgets/transcriber"
    click UI4 "https://github.com/chidiwilliams/buzz/tree/main/buzz/widgets/transcription_viewer"
    
    click T1 "https://github.com/chidiwilliams/buzz/blob/main/buzz/transcriber/file_transcriber.py"
    click T2 "https://github.com/chidiwilliams/buzz/blob/main/buzz/transcriber/recording_transcriber.py"
    click T3 "https://github.com/chidiwilliams/buzz/blob/main/buzz/transcriber/whisper_cpp.py"
    click T4 "https://github.com/chidiwilliams/buzz/blob/main/buzz/transcriber/whisper_file_transcriber.py"
    click T5 "https://github.com/chidiwilliams/buzz/blob/main/buzz/transcriber/openai_whisper_api_file_transcriber.py"
    
    click D1 "https://github.com/chidiwilliams/buzz/blob/main/buzz/db/db.py"
    click D2 "https://github.com/chidiwilliams/buzz/tree/main/buzz/db"
    click D3 "https://github.com/chidiwilliams/buzz/blob/main/buzz/db/migrator.py"
    
    click S1 "https://github.com/chidiwilliams/buzz/tree/main/buzz/assets"
    click S2 "https://github.com/chidiwilliams/buzz/tree/main/buzz/locale"
    click S3 "https://github.com/chidiwilliams/buzz/tree/main/buzz/settings"
    click S4 "https://github.com/chidiwilliams/buzz/blob/main/buzz/store/keyring_store.py"
    
    click C1 "https://github.com/chidiwilliams/buzz/blob/main/buzz/cli.py"
    click C2 "https://github.com/chidiwilliams/buzz/blob/main/buzz/__main__.py"

    %% Style Classes
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef transcription fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef db fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef settings fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef cli fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
