# luis-munu/oghma_translator architecture

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

- Interactive diagram: https://gitdiagram.com/luis-munu/oghma_translator
- Repository: https://github.com/luis-munu/oghma_translator

## Overview

##### Project Type and Purpose
- This is a specialized, single-purpose translation tool designed to process a comprehensive document (“Oghma”) and translate its contents into multiple languages using AI-driven asynchronous API calls.
- The README confirms it’s primarily aimed at translating data from Excel sheets (and related JSON prompt files) into various languages using a DeepSeek (or compatible OpenAI) API.

##### Key Components
- Configuration Layer:
- .env file: Contains API keys and model configuration.
- src/config.py: Houses settings like supported languages, file paths, and model parameters.
- Data Management:
- Input Data: Files inside the data folder (Excel files and JSON files – prompts, terms, note patterns).
- Output Data: Translated Excel files stored in the output folder.
- Core Translation Engine:
- src/main.py: Likely serves as the entry point coordinating the entire translation process.
- src/translator.py: Implements the logic that communicates with the DeepSeek/OpenAI API for translation.
- src/translation_tasks.py: Manages tasks, potentially organizing asynchronous calls so that translation can resume if interrupted.
- src/progress.py: Handles tracking of translation progress, which is useful for long-running processes.
- Third-Party API Integration:
- The system leverages external AI models (DeepSeek by default) via API calls to perform its translation tasks.

##### Relationships and Data Flow
- The configuration layer initializes settings and API keys (from .env and config.py).
- The Data Ingestion component reads original data from the input Excel and JSON files in the data directory.
- The main logic (in main.py) orchestrates the overall flow:
- It loads configuration and input data.
- It delegates translation jobs to the translator component, which uses asynchronous calls (organized by translation_tasks.py) to communicate with the external API.
- Progress is monitored through the progress module, allowing tasks to be resumed if stopped.
- Once translation is complete, output files are generated and written to the output folder.

##### Architectural Patterns and Principles
- Modular Design: Separation of configuration, data handling, translation logic, and progress monitoring.
- Asynchronous Processing: Utilizes asynchronous API calls to improve efficiency.
- Separation of Concerns: Configurations and API credentials are kept separate from the business logic, and data I/O is clearly isolated.
- Extendability: The design allows changes like adding new languages or adjusting prompt logic with minimal code modifications (thanks to the clear division in configuration and translation task files).

##### Recommended Detail Level
- Be explicit about the functions of each major module, and ensure that any asynchronous interactions (like resilient translation calls through translation_tasks.py) are represented.
- Essence of each critical part – from setup (loading API keys and parameters) to the translation process (asynchronous calls and progress checking) to the final output generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration"
        ENV[".env"]:::config
        CONFIG["src/config.py"]:::config
    end

    %% Data Management Layer
    subgraph "Data Management"
        subgraph "Input Data"
            INP_FOLDER["Data Folder"]:::data
            FILE1["Project Oghma - short.xlsx"]:::data
            FILE2["Project Oghma.xlsx"]:::data
            FILE3["knowledge.json"]:::data
            FILE4["note_patterns.json"]:::data
            FILE5["prompts.json"]:::data
            FILE1 --> INP_FOLDER
            FILE2 --> INP_FOLDER
            FILE3 --> INP_FOLDER
            FILE4 --> INP_FOLDER
            FILE5 --> INP_FOLDER
        end
        OUTPUT["Data Output (Translated Excel)"]:::data
    end

    %% Translation Engine Layer
    subgraph "Translation Engine"
        MAIN["src/main.py"]:::logic
        TRANSLATOR["src/translator.py"]:::logic
        TASKS["src/translation_tasks.py"]:::logic
        PROGRESS["src/progress.py"]:::logic
    end

    %% External API Service
    API("DeepSeek/OpenAI API"):::api

    %% Connections
    ENV -->|"configuration_settings"| MAIN
    CONFIG -->|"configuration_settings"| MAIN
    INP_FOLDER -->|"raw_document_data"| MAIN
    MAIN -->|"start_translation"| TRANSLATOR
    TRANSLATOR -->|"manage_async_tasks"| TASKS
    TASKS -->|"API_call"| API
    API -->|"response"| TRANSLATOR
    TRANSLATOR -->|"progress_update"| PROGRESS
    TRANSLATOR -->|"translated_content"| OUTPUT

    %% Click Events
    click ENV "https://github.com/luis-munu/oghma_translator/blob/main/.env"
    click CONFIG "https://github.com/luis-munu/oghma_translator/blob/main/src/config.py"
    click FILE1 "https://github.com/luis-munu/oghma_translator/blob/main/data/Project Oghma - short.xlsx"
    click FILE2 "https://github.com/luis-munu/oghma_translator/blob/main/data/Project Oghma.xlsx"
    click FILE3 "https://github.com/luis-munu/oghma_translator/blob/main/data/knowledge.json"
    click FILE4 "https://github.com/luis-munu/oghma_translator/blob/main/data/note_patterns.json"
    click FILE5 "https://github.com/luis-munu/oghma_translator/blob/main/data/prompts.json"
    click MAIN "https://github.com/luis-munu/oghma_translator/blob/main/src/main.py"
    click TRANSLATOR "https://github.com/luis-munu/oghma_translator/blob/main/src/translator.py"
    click TASKS "https://github.com/luis-munu/oghma_translator/blob/main/src/translation_tasks.py"
    click PROGRESS "https://github.com/luis-munu/oghma_translator/blob/main/src/progress.py"
    click OUTPUT "https://github.com/luis-munu/oghma_translator/tree/main/output"

    %% Styles
    classDef config fill:#f2c80f,stroke:#333,stroke-width:2px,color:#000;
    classDef data fill:#99d9ea,stroke:#333,stroke-width:2px;
    classDef logic fill:#d1e4aa,stroke:#333,stroke-width:2px;
    classDef api fill:#fdbb84,stroke:#333,stroke-width:2px,font-style:italic;
```
