# xapajiamnu/translatelocally architecture

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

- Interactive diagram: https://gitdiagram.com/xapajiamnu/translatelocally
- Repository: https://github.com/xapajiamnu/translatelocally

## Overview

##### Project Type and Purpose
- This is a native Qt-based desktop application (C++17) with both GUI and CLI interfaces.
- It embeds the Marian/Bergamot translation engine, manages local translation models, and can serve as a Native Messaging host for browser extensions.
- It provides translation services entirely on the user’s machine, including model download, management, and translation pipelines (pivoting, quantization).

##### High-Level Architecture Overview
Break the system into four logical layers:
A. Presentation Layer (User Interfaces)
- GUI Module (Qt Widgets)
– mainwindow.ui, dialogs under src/settings, UI controllers (mainwindow.cpp, TranslatorSettingsDialog)
- CLI Module
– CLI parsing (CLIParsing.h), CommandLineIface, NativeMsgIface, NativeMsgManager
B. Core Application Logic
- Model Manager (inventory/ModelManager) – tracks installed models on disk
- Translation Controller (Translation.cpp/h, AlignmentWorker, AlignmentHighlighter)
- Network & Download Manager (Network.cpp/h) – HTTP download via Qt Network, wrapping libarchive for extraction
C. Translation Engine Integration
- MarianInterface (src/MarianInterface.cpp/h) – C++ wrapper over bergamot-translator (submodule in 3rd_party)
- 3rd_party/bergamot-translator – the actual inference engine
D. Build & Packaging Toolchain
- CMake project files (CMakeLists.txt, cmake/ directory)
- Packaging scripts (dist/, logo/) for .dmg, AppImage, PKGBUILD, Windows resources

##### Component Relationships and Data Flows
- GUI or CLI receives a user request → forwards to Core Translation Controller
- Controller queries Model Manager for model path → invokes MarianInterface
- MarianInterface calls into bergamot-translator binary/API → returns tokens/strings
- Controller posts results back to GUI view or CLI stdout
- For model download: Core invokes Network module → HTTP GET → libarchive extraction → updates Model Manager
- Native Messaging: NativeMsgManager wraps the CLI controller, exposing JSON in/out

##### Key Architectural Patterns & Principles
- MVC/MVP style in the GUI: UI files define Views, mainwindow.cpp & dialogs act as Controllers, ModelManager is the Model
- Single-process monolith but logically layered (UI / Core Logic / Engine)
- Dependency injection via CMake: choice of BLAS provider (MKL vs OpenBLAS), Qt version, external archives
- Plugin-style support for multiple model repositories: repository definitions loaded at runtime

##### Important Technologies & Frameworks
- Qt ≥5 (Widgets, Network, LinguisticTool, SVG)
- CMake build system, custom cmake modules for packaging and versioning
- Intel MKL (preferred BLAS) or optionally OpenBLAS
- libarchive for model tarball extraction
- bergamot-translator (Marian fork) for the core MT engine
- Native Messaging protocol (JSON over stdin/stdout)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User"]:::external
        GUI["GUI Module\n(Qt Widgets)"]:::ui
        CLI["CLI Module"]:::ui
        NativeMsg["NativeMsg Host"]:::ui
    end

    %% Core Logic Layer
    subgraph "Core Application Logic"
        direction TB
        TC["Translation Controller"]:::core
        MM["Model Manager"]:::core
        Network["Network Module\n(QtNetwork + libarchive)"]:::core
        Archive["Archive Extractor\n(libarchive)"]:::core
    end

    %% Engine Integration Layer
    subgraph "Translation Engine Integration"
        direction TB
        MI["MarianInterface"]:::engine
        Engine["bergamot-translator Engine"]:::engine
    end

    %% External Dependencies
    subgraph "External"
        direction TB
        FS["File System\n(models on disk)"]:::external
        Repos["External Repositories\n(HTTP endpoints)"]:::external
    end

    %% Packaging Layer
    subgraph "Build & Packaging Toolchain"
        direction TB
        Entry["Application Entry\nPoint (main.cpp)"]:::packaging
        CMake["CMakeLists.txt"]:::packaging
        CMakeDir["cmake/"]:::packaging
        Dist["dist/"]:::packaging
        Logo["logo/"]:::packaging
    end

    %% Flows
    User -->|"1: Translate Request"| GUI
    User -->|"1: Translate Request"| CLI
    CLI -->|"JSON over stdin/stdout"| NativeMsg
    GUI -->|"Qt Signals/Slots"| TC
    CLI -->|"CLI Call"| TC
    NativeMsg -->|"Invoke Controller"| TC

    TC -->|"2: Query Model"| MM
    MM -->|"Read/Write"| FS

    TC -->|"3: Translate API"| MI
    MI -->|"C++ API"| Engine
    Engine -->|"Return Tokens"| MI
    MI -->|"Return Text"| TC

    TC -->|"4: Download Request"| Network
    Network -->|"HTTP GET"| Repos
    Network -->|"Extract"| Archive
    Archive -->|"Update"| MM

    Entry --> GUI
    Entry --> CLI

    %% Packaging flows
    CMake --> CMakeDir
    CMake --> Dist
    CMake --> Logo

    %% Click Events
    click GUI "https://github.com/xapajiamnu/translatelocally/blob/master/src/mainwindow.ui"
    click CLI "https://github.com/xapajiamnu/translatelocally/blob/master/src/cli/CLIParsing.h"
    click NativeMsg "https://github.com/xapajiamnu/translatelocally/blob/master/src/cli/NativeMsgManager.cpp"
    click TC "https://github.com/xapajiamnu/translatelocally/blob/master/src/Translation.cpp"
    click MM "https://github.com/xapajiamnu/translatelocally/blob/master/src/inventory/ModelManager.cpp"
    click Network "https://github.com/xapajiamnu/translatelocally/blob/master/src/Network.cpp"
    click Archive "https://github.com/xapajiamnu/translatelocally/blob/master/src/Network.cpp"
    click MI "https://github.com/xapajiamnu/translatelocally/blob/master/src/MarianInterface.cpp"
    click Engine "https://github.com/xapajiamnu/translatelocally/tree/master/3rd_party/bergamot-translator/"
    click Entry "https://github.com/xapajiamnu/translatelocally/blob/master/src/main.cpp"
    click CMake "https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt"
    click CMakeDir "https://github.com/xapajiamnu/translatelocally/tree/master/cmake/"
    click Dist "https://github.com/xapajiamnu/translatelocally/tree/master/dist/"
    click Logo "https://github.com/xapajiamnu/translatelocally/tree/master/logo/"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef engine fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef packaging fill:#C0C0C0,stroke:#333,stroke-width:1px
```
