# olivierlavaud/l2t architecture

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

- Interactive diagram: https://gitdiagram.com/olivierlavaud/l2t
- Repository: https://github.com/olivierlavaud/l2t

## Overview

##### Project type and purpose
- L2T is an open-source, modular command-line translation tool that uses Meta’s NLLB-200 neural model to translate text and documents between 200+ languages.
- It’s not a full-stack web app or compiler, but rather a CLI application exposing a pipeline: CLI parser → main orchestration → language detection/translation → output generation.

##### File structure
Top-level
- app/              ← core Python package
- docs/             ← example documents
- gpu/              ← GPU detection and sync helper scripts
- img/, l2t-alias.ps1 ← assets & convenience scripts
- pyproject.toml, requirements.txt ← project config and dependencies
app/ package
- cli.py            ← CLI argument parsing (click/argparse)
- main.py           ← central orchestrator: wires together handlers
- file_handlers.py  ← I/O for plain text & PDFs
- translator.py     ← wraps HuggingFace NLLB-200 model calls
- optimizations.py  ← batching, caching, performance tweaks
- logger.py         ← logging configuration
- utils.py          ← shared helpers (language code validation, path helpers)
- minimal/          ← small example scripts and tests for minimal configs

##### README for additional insights
- Describes installation (uv package manager), alias setup, usage patterns.
- Lists features: list languages, translate text or files, specify input/output.
- Mentions HuggingFace CLI access, GPU requirements.

a. Main components
- CLI Layer: `cli.py` invoked via `l2t` or uv run
- Orchestrator: `main.py`
- I/O Subsystem: `file_handlers.py`
- Translation Engine: `translator.py` + NLLB-200 model
- Performance/Optimization: `optimizations.py`
- Logging: `logger.py`
- Utility Functions: `utils.py`
- GPU Helpers: scripts under `gpu/`
- External Dependencies: HuggingFace model hub, PyTorch/transformers, UV runner
b. Relationships & interactions
1. User types command → CLI Layer parses arguments.
2. CLI calls Orchestrator with parameters.
3. Orchestrator:
- Validates languages via utils
- Uses file_handlers to read input (text/PDF) or accepts inline text
- Delegates to translator module
- translator loads or retrieves NLLB-200 model from HuggingFace (possibly cached)
- translator calls optimizations for batching or GPU management
- Receives translated text
- If file output requested, file_handlers writes result
- Logs operations via logger
4. GPU scripts live aside for pre-checks (optional start-up step).
c. Architectural patterns & design principles
- Modular layering: separate CLI, core orchestration, I/O, translation, logging, utilities.
- Single Responsibility: each module has a clear role.
- Pipeline pattern: sequential processing stages.
- Lazy loading / caching of large ML models.
d. Key technologies/frameworks
- Python 3.x
- HuggingFace Transformers & Tokenizers (NLLB-200)
- PyTorch (for GPU execution)
- uv: project runner
- click/argparse (CLI)
- PDF parsing library (e.g., PyPDF2 or pdfminer, implied in file_handlers)

[CLI] → [Orchestrator] → [File I/O]
↘ [Translator] → [NLLB-200 Model Hub]
↘ [Optimizations]
- Green: core modules (Orchestrator, Translator)
- Blue: I/O (File Handlers, CLI)
- Orange: performance (Optimizations, GPU scripts)
- Gray: utilities (Logger, Utils)
- Purple: external dependencies (HuggingFace, PyTorch)
- Labels on components: module name + key responsibilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and Components
    subgraph "CLI Layer"
        CLI["CLI Layer<br/>(cli.py)"]:::io
    end

    subgraph "Core Modules"
        ORCH["Orchestrator<br/>(main.py)"]:::core
        TR["Translator<br/>(translator.py)"]:::core
    end

    subgraph "I/O Subsystem"
        FH["File Handlers<br/>(file_handlers.py)"]:::io
    end

    subgraph "Performance & GPU"
        OPT["Optimizations<br/>(optimizations.py)"]:::perf
        GPU["GPU Helpers<br/>(gpu/)"]:::perf
    end

    subgraph "Utilities"
        LOG["Logger<br/>(logger.py)"]:::util
        UTIL["Utils<br/>(utils.py)"]:::util
    end

    subgraph "Demo & Test"
        MIN["Minimal Scripts<br/>(app/minimal/)"]:::demo
    end

    subgraph "External Dependencies"
        HF["HuggingFace Model Hub"]:::external
        PT["PyTorch/Transformers"]:::external
        UV["UV Runner"]:::external
    end

    subgraph "Model Cache"
        Cache[(Model Cache)]:::storage
    end

    %% Flow
    UV -->|"invokes"| CLI
    CLI -->|"parses args"| ORCH
    CLI -->|"runs demos"| MIN
    ORCH -->|"validate languages"| UTIL
    ORCH -->|"log operations"| LOG
    ORCH -->|"read input"| FH
    FH -->|"file content"| ORCH
    ORCH -->|"invoke translation"| TR
    TR -->|"apply batching"| OPT
    OPT -->|"optimized inputs"| TR
    TR -->|"load/cache model"| Cache
    TR -->|"fetch model"| HF
    TR -->|"use frameworks"| PT
    TR -->|"translation result"| ORCH
    ORCH -->|"write output"| FH
    GPU -.->|"optional pre-check"| ORCH

    %% Click Events
    click CLI "https://github.com/olivierlavaud/l2t/blob/master/app/cli.py"
    click ORCH "https://github.com/olivierlavaud/l2t/blob/master/app/main.py"
    click FH "https://github.com/olivierlavaud/l2t/blob/master/app/file_handlers.py"
    click TR "https://github.com/olivierlavaud/l2t/blob/master/app/translator.py"
    click OPT "https://github.com/olivierlavaud/l2t/blob/master/app/optimizations.py"
    click LOG "https://github.com/olivierlavaud/l2t/blob/master/app/logger.py"
    click UTIL "https://github.com/olivierlavaud/l2t/blob/master/app/utils.py"
    click GPU "https://github.com/olivierlavaud/l2t/tree/master/gpu/"
    click MIN "https://github.com/olivierlavaud/l2t/tree/master/app/minimal/"

    %% Styles
    classDef core fill:#b2f2bb,stroke:#239a3b,color:#000
    classDef io fill:#bae7ff,stroke:#1890ff,color:#000
    classDef perf fill:#ffd8a8,stroke:#fa8c16,color:#000
    classDef util fill:#d9d9d9,stroke:#595959,color:#000
    classDef external fill:#efdbff,stroke:#9254de,color:#000
    classDef storage fill:#ffc069,stroke:#d46b08,color:#000
    classDef demo fill:#e6fffb,stroke:#13c2c2,color:#000
```
