# himandrobot/stremio-translate-subtitle-by-geanpn architecture

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

- Interactive diagram: https://gitdiagram.com/himandrobot/stremio-translate-subtitle-by-geanpn
- Repository: https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn

## Overview

##### Main Components
- Stremio Integration / Add-on Server: Files such as index.js, connection.js, manifest.json, and package.json suggest that this is the entry point and configuration for integrating with Stremio via stremio-addon-sdk.
- Subtitle Management: Modules like subtitles.js and processfiles.js handle the parsing, chunking, and reassembling of subtitle files. The system also checks the filesystem cache to avoid redundant translations.
- Translation Providers & Handlers: Files such as translateProvider.js, languages.js, and the JSON files under langs indicate support for multiple translation providers and language configuration.
- Queue System: The queues/translationQueue.js file (using the better-queue library as noted in the README) is responsible for managing asynchronous translation tasks, retries, and provider rotation.
- External API Integrations: modules like opensubtitles.js manage communication with external subtitle services (i.e., OpenSubtitlesV3), while translation logic wraps various translation APIs (and web scraping methods for Google Translate Free).
- Configuration & Environment: The use of environment variables and the manifest.json file ensure that the add-on is configurable (e.g., server PORT, BASE_URL) and compatible with Stremio’s add-on architecture.

##### Architectural Patterns and Principles
- Modular Separation: Each major function – fetching, queuing, processing, and translating – is clearly separated into files and modules.
- Asynchronous Processing: The queue system (better-queue) signifies an asynchronous, decoupled architecture to handle translation tasks in parallel.
- Fallback & Resilience: The translation provider selection with fallback and rotation indicates robustness against API failures or rate limits.
- Caching: The filesystem-based caching mechanism ensures improved performance and reduced redundant API calls.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Stremio Client"]:::client

    subgraph "Stremio Add-on Server"
        SE["Add-on Server Entry"]:::server
        CN["Connection Manager"]:::server
        MF["Manifest Config"]:::server
        PK["Package Config"]:::server
    end

    A -->|"request"| SE
    SE --> CN
    CN --> MF
    MF --> PK
    PK --> LCT["Local Filesystem Cache"]:::processing

    LCT -->|"cache-miss"| SF["Subtitle Fetcher (opensubtitles.js)"]:::processing
    SF --> TQ["Translation Queue (queues/translationQueue.js)"]:::processing

    subgraph "Translation Providers"
        PG["Translation Gateway (translateProvider.js)"]:::processing
        LC["Language Config (languages.js)"]:::processing
        BL["Base Language Config"]:::processing
        CG["ChatGPT Language Config"]:::processing
        GG["GoogleTranslateFree Config"]:::processing
        PG --> LC
        LC --> BL
        BL --> CG
        CG --> GG
    end

    TQ --> PG
    GG --> SP["Subtitle Parser (subtitles.js)"]:::processing
    SP --> FP["File Chunker (processfiles.js)"]:::processing
    FP --> SR["Add-on Server Response"]:::server
    SR -->|"respond"| A

    EL["External Libraries\n(stremio-addon-sdk, better-queue)"]:::external
    SE --- EL
    TQ --- EL

    click SE "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/index.js"
    click CN "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/connection.js"
    click MF "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/manifest.json"
    click PK "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/package.json"
    click SF "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/opensubtitles.js"
    click TQ "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/queues/translationQueue.js"
    click PG "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/translateProvider.js"
    click LC "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/languages.js"
    click BL "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/langs/base.lang.json"
    click CG "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/langs/translateChatGpt.lang.json"
    click GG "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/langs/translateGoogleFree.lang.json"
    click SP "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/subtitles.js"
    click FP "https://github.com/himandrobot/stremio-translate-subtitle-by-geanpn/blob/main/processfiles.js"

    classDef client fill:#F9E79F,stroke:#B7950B,stroke-width:2;
    classDef server fill:#AED6F1,stroke:#2E86C1,stroke-width:2;
    classDef processing fill:#ABEBC6,stroke:#27AE60,stroke-width:2;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2;
```
