# hu-ke/gemini-video-subtitle architecture

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

- Interactive diagram: https://gitdiagram.com/hu-ke/gemini-video-subtitle
- Repository: https://github.com/hu-ke/gemini-video-subtitle

## Overview

##### Main Components
- Browser Extension Shell – The project is strictly an extension. Break it into its high-level parts:
○ Background Scripts – “src/browser-extension/background”: Handles background tasks and possibly API communication.
○ Content Scripts – “src/browser-extension/content_script”: Injected into web pages to capture and process audio/video streams and manage UI overlays (e.g., InnerContainer, TitleBar).
○ UI Interfaces:
▪ Popup – “src/browser-extension/popup”: The small extension window (with components like Settings and InnerSettings) for quick interactions.
▪ Options – “src/browser-extension/options”: A dedicated configuration page (index.html, index.tsx, index.css) where users set up their Gemini API Key.
○ Shared Components and Utilities – “src/browser-extension/common” and “src/browser-extension/utils”: Contains React components, hooks (e.g., useTheme, useSettings), styles, and utility functions that support multiple parts of the extension.
- External Service:
○ Gemini API – The extension depends on a Gemini API key for transcription and translation. This external call is a key dependency.
- Build and Configuration:

##### Out Interactions and Relationships
- Content Script ↔ Background Script:
- Messaging channels (likely via browser.runtime or similar APIs) where content scripts (collecting audio or user actions) communicate with the background for processing.
- Background Script ↔ Gemini API:
- Popup/Options UI ↔ Background Script:
- Common Utilities & Shared Components:
- That both the content scripts and the UI components rely on shared React components (forms, hooks, error fallbacks) indicating code reuse and consistency in state and look and feel.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Modularity:
- “common” folder as a shared utility hub that supports the different modules (show connectors highlighting dependency).
- Messaging and Asynchronous Communication:
- Use of browser extension messaging patterns for inter-component communication.
- External API Integration:
- External Gemini API communication, noting that it forms the critical external dependency for real-time transcription and translation.

##### Specific Technologies and Libraries
- TypeScript and React – The code uses .tsx files and TypeScript, implying component-based design and type safety.
- Vite – As seen in the Vite config, indicating modern bundling and fast development cycles.
- Browser Extension APIs – Implicit in the manifest and the structure (background, content script, popup, options) so include a “Browser API” component where needed.
- Gemini Multimodal – As the key external service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Extension Core"
        B["Background Script"]:::bg
        C["Content Script (captures media & injects UI overlay)"]:::cs
        CP["Media Processing Library"]:::med
    end

    subgraph "UI Layer"
        P["Popup UI"]:::ui
        O["Options UI"]:::ui
    end

    subgraph "Shared Components & Utilities"
        COM["Common Components & Hooks"]:::shared
        UTILS["Utility Functions"]:::shared
    end

    E["Gemini API"]:::external
    BA["Browser APIs"]:::external

    C -->|"messaging"| B
    B -->|"transcription/translation_requests"| E
    E -->|"responses"| B
    P -->|"config_data"| B
    O -->|"config_data"| B

    C -->|"uses_components"| COM
    C -->|"uses_utilities"| UTILS
    P -->|"uses_components"| COM
    P -->|"uses_utilities"| UTILS
    O -->|"uses_components"| COM
    O -->|"uses_utilities"| UTILS

    C -->|"processes_media"| CP

    B ---|"extension_environment"| BA
    C ---|"content_access"| BA

    click B "https://github.com/hu-ke/gemini-video-subtitle/blob/main/src/browser-extension/background/index.ts"
    click C "https://github.com/hu-ke/gemini-video-subtitle/tree/main/src/browser-extension/content_script"
    click P "https://github.com/hu-ke/gemini-video-subtitle/tree/main/src/browser-extension/popup"
    click O "https://github.com/hu-ke/gemini-video-subtitle/tree/main/src/browser-extension/options"
    click COM "https://github.com/hu-ke/gemini-video-subtitle/tree/main/src/browser-extension/common"
    click UTILS "https://github.com/hu-ke/gemini-video-subtitle/tree/main/src/browser-extension/utils"
    click CP "https://github.com/hu-ke/gemini-video-subtitle/tree/main/src/browser-extension/content_script/lib"
    click E "https://github.com/hu-ke/gemini-video-subtitle/tree/main/src/browser-extension/content_script/contexts"

    classDef bg fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef cs fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef ui fill:#f94144,stroke:#333,stroke-width:2px;
    classDef shared fill:#277da1,stroke:#333,stroke-width:2px;
    classDef med fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef external fill:#577590,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
```
