# ijazsadiqbasha/whispr-electron architecture

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

- Interactive diagram: https://gitdiagram.com/ijazsadiqbasha/whispr-electron
- Repository: https://github.com/ijazsadiqbasha/whispr-electron

## Overview

##### Main Components
- Electron Main Process:
- Entry point: src/main.ts.
- Responsible for bootstrapping the application, handling global events (like global shortcuts), and managing inter-process communications.
- Renderer Process:
- Entry point: src/renderer.ts with supporting UI components in src/components and pages in src/pages.
- Uses React/TypeScript (components such as ThemeProvider.tsx, ui inputs, etc.) to create an interactive user interface including the overlay and settings pages.
- Native/Platform-Specific Components:
- Provided binaries (bin/MacKeyServer, bin/WinKeyServer.exe, bin/X11KeyServer) for handling system-level key capture or audio operations across platforms.
- Transcription Engine:
- Whisper model-related files (bin/whisper_base containing model.bin, config.json, tokenizer.json, etc.) that power the core speech-to-text processing.
- Supporting Libraries:
- Audio conversion and utility functions found in src/lib (e.g., audioConvert.ts, utils.ts) that handle audio processing and other helper operations.

##### Relationships and Interactions
- Flow from user interaction (triggering recording via UI) in the Renderer to the transcription engine, either by direct calls or through backend orchestration.
- Integration of the Whisper transcription engine: the Main or a dedicated service might pass audio data from the Recorder (within the Renderer/Post-capture in Main) to the Whisper binaries/model for transcription.
- Connections to external services (if any) such as clipboard integration, although this is primarily a local, packaged application.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Differentiate clearly between UI components (src/components, src/pages) and backend processing (Electron Main Process and native binaries).
- Cross-Platform Support: Emphasize the usage of platform-specific binaries in the bin folder for handling system-level operations.
- Modularization: Note that the project is partitioned into logical modules (e.g., UI, libraries, audio conversion, transcription models) that ensure code reusability and easier testing.

##### Relevant Technologies and Frameworks
- Electron – for building cross-platform desktop applications.
- TypeScript/React – for the renderer’s UI development (evidenced by .tsx files and component structure).
- Tailwind CSS – suggested by tailwind.config.cjs and globals.css in the renderer folder.
- Whisper Model – as the transcription engine with model files located under bin/whisper_base.
- Vite – used for bundling/building the project (vite.config.ts and tsconfig.json are present).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Layer
    subgraph "Backend Layer"
        EM["Electron Main Process"]:::backend
        NS1["macOS Key Server"]:::native
        NS2["Windows Key Server"]:::native
        NS3["Linux/X11 Key Server"]:::native
        TE["Whisper Transcription Engine"]:::engine
        AL["Audio Conversion & Utilities"]:::lib
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        RP["Renderer Process"]:::frontend
        UC["UI Components"]:::frontend
        OP["Overlay Page"]:::frontend
        SP["Settings Page"]:::frontend
    end

    %% Interactions
    RP -->|"IPC"| EM
    UC -->|"UserInteraction"| RP
    EM -->|"TriggerTranscription"| TE
    EM -->|"GlobalShortcut"| NS1
    EM -->|"GlobalShortcut"| NS2
    EM -->|"GlobalShortcut"| NS3
    EM -->|"ProcessAudio"| AL
    AL -->|"AudioData"| TE
    TE -->|"TranscriptionResult"| RP

    %% Click Events
    click EM "https://github.com/ijazsadiqbasha/whispr-electron/blob/master/src/main.ts"
    click RP "https://github.com/ijazsadiqbasha/whispr-electron/blob/master/src/renderer.ts"
    click UC "https://github.com/ijazsadiqbasha/whispr-electron/tree/master/src/components"
    click OP "https://github.com/ijazsadiqbasha/whispr-electron/blob/master/src/pages/Overlay.tsx"
    click SP "https://github.com/ijazsadiqbasha/whispr-electron/blob/master/src/pages/Settings.tsx"
    click NS1 "https://github.com/ijazsadiqbasha/whispr-electron/tree/master/bin/MacKeyServer"
    click NS2 "https://github.com/ijazsadiqbasha/whispr-electron/blob/master/bin/WinKeyServer.exe"
    click NS3 "https://github.com/ijazsadiqbasha/whispr-electron/tree/master/bin/X11KeyServer"
    click TE "https://github.com/ijazsadiqbasha/whispr-electron/tree/master/bin/whisper_base"
    click AL "https://github.com/ijazsadiqbasha/whispr-electron/tree/master/src/lib"

    %% Styles
    classDef backend fill:#f4c2c2,stroke:#333,stroke-width:2px;
    classDef frontend fill:#c2d6f4,stroke:#333,stroke-width:2px;
    classDef native fill:#c2f4c2,stroke:#333,stroke-width:2px;
    classDef engine fill:#f4e1c2,stroke:#333,stroke-width:2px;
    classDef lib fill:#e1c2f4,stroke:#333,stroke-width:2px;
```
