# ao-chii/nextranslation architecture

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

- Interactive diagram: https://gitdiagram.com/ao-chii/nextranslation
- Repository: https://github.com/ao-chii/nextranslation

## Overview

##### Project type and purpose
- From the file tree (“src/nex_translation”) and the README title “NexTranslation,” this is a Python-based document translation application.
- It provides both a CLI and a GUI front end, reads input documents (PDFs), processes them, sends text to an external translator (Google Translate), and renders translated output.

##### File structure
- Top-level artifacts:
- pyproject.toml (build & dependency manager)
- config.json (runtime configuration)
- docs/ (design docs, layered architecture description)
- src/nex_translation/ (application code)
- tests/ (unit tests and sample PDFs)
- Within src/nex_translation the code is organized by layers:
- presentation/ (cli.py, gui.py)
- core/ (converter.py, doclayout.py, pdf_processor.py, pdfinterpreter.py, translator.py, google_translator.py)
- infrastructure/ (cache.py, config.py)
- utils/ (exceptions.py, logger.py)

##### README and docs
- README is minimal, but docs/LayeredAchitecture.md and docs/layer_architecture.md confirm a classic layered architecture model.

– Presentation layer: CLI module and GUI module
– Core / Business Logic layer:
· PDFInterpreter (parses PDFs into text & structure)
· PDFProcessor (extracts pages, images, text blocks)
· Converter & DocLayout (rebuilds translated text into PDF layout)
· Translator (orchestrates translation workflow)
· GoogleTranslator (wraps calls to Google Translate API)
– Infrastructure layer:
· Config (reads config.json)
· Cache (stores intermediate translations for performance)
– Utilities:
· Logger (centralized logging)
· Exception handlers
– External services: Google Translate API
– Data stores (if any): local cache store on disk

– Presentation → Core.Translator.start()
– Translator → PDFInterpreter → PDFProcessor → returns document model
– Translator → GoogleTranslator (with caching via Infrastructure.Cache)
– Translator → Converter/DocLayout → writes output file
– All layers may call Utils.Logger/Exceptions
– Config is read at startup and injected into all layers

c. Architectural patterns and principles:
– Layered architecture (Presentation, Core, Infrastructure, Utils)
– Dependency inversion: Core not tied directly to CLI/GUI or to cache implementation
– Single Responsibility: each module has a well-defined role
– Externalized configuration (config.json) and caching for idempotent external API calls

d. Key technologies and frameworks:
– Python 3 (pyproject.toml)
– CLI argument parsing (in cli.py)
– GUI toolkit (as implemented in gui.py)
– Google Translate REST API
– PDF parsing library (pdfinterpreter.py likely wraps a third-party lib)
– Logging and exception utilities

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Documentation"
        DocsOverview["Project Overview\n(docs/ProjectOverview.md)"]
        DocsLayers1["Layered Architecture\n(docs/LayeredAchitecture.md)"]
        DocsLayers2["Layered Architecture\n(docs/layer_architecture.md)"]
        DocsReqs["Requirements\n(docs/Requirements.md)"]
    end

    subgraph "Configuration & Build"
        ConfigFile["config.json"]:::infra
        BuildFile["pyproject.toml"]:::infra
    end

    subgraph "Presentation Layer"
        CLI["CLI Module\n(cli.py)"]:::presentation
        GUI["GUI Module\n(gui.py)"]:::presentation
    end

    subgraph "Core Layer"
        Translator["Translator Orchestrator\n(translator.py)"]:::core
        PDFInterp["PDFInterpreter\n(pdfinterpreter.py)"]:::core
        PDFProc["PDFProcessor\n(pdf_processor.py)"]:::core
        GoogleTrans["GoogleTranslator\n(google_translator.py)"]:::core
        Converter["Converter\n(converter.py)"]:::core
        DocLayout["DocLayout\n(doclayout.py)"]:::core
    end

    subgraph "Infrastructure Layer"
        ConfigLoader["Configuration Loader\n(config.py)"]:::infra
        CacheStore["Cache Store\n(cache.py)"]:::infra
    end

    subgraph "Utilities"
        Logger["Logger\n(logger.py)"]:::utils
        Exceptions["Exception Definitions\n(exceptions.py)"]:::utils
    end

    ExternalAPI["Google Translate API"]:::external

    %% Relationships
    ConfigFile -->|loads| ConfigLoader
    ConfigLoader -->|provides config| CLI
    ConfigLoader -->|provides config| GUI
    ConfigLoader -->|provides config| Translator

    CLI -->|starts translation| Translator
    GUI -->|starts translation| Translator

    Translator -->|parse PDF| PDFInterp
    PDFInterp -->|extract elements| PDFProc
    PDFProc -->|returns doc model| Translator

    Translator -->|translate text| GoogleTrans
    GoogleTrans -->|calls API| ExternalAPI
    Translator -->|uses cache| CacheStore
    GoogleTrans -->|caches results| CacheStore

    Translator -->|rebuild PDF| Converter
    Converter -->|layout pages| DocLayout

    %% Utilities usage
    CLI -->|logs/errors| Logger
    GUI -->|logs/errors| Logger
    Translator -->|logs/errors| Logger
    PDFInterp -->|logs/errors| Logger
    PDFProc -->|logs/errors| Logger
    GoogleTrans -->|logs/errors| Logger
    Converter -->|logs/errors| Logger
    DocLayout -->|logs/errors| Logger

    CLI -->|raises| Exceptions
    GUI -->|raises| Exceptions
    Translator -->|raises| Exceptions
    PDFInterp -->|raises| Exceptions
    PDFProc -->|raises| Exceptions
    GoogleTrans -->|raises| Exceptions
    Converter -->|raises| Exceptions
    DocLayout -->|raises| Exceptions

    %% Click Events
    click CLI "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/presentation/cli.py"
    click GUI "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/presentation/gui.py"
    click PDFInterp "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/core/pdfinterpreter.py"
    click PDFProc "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/core/pdf_processor.py"
    click Converter "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/core/converter.py"
    click DocLayout "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/core/doclayout.py"
    click Translator "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/core/translator.py"
    click GoogleTrans "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/core/google_translator.py"
    click ConfigLoader "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/infrastructure/config.py"
    click CacheStore "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/infrastructure/cache.py"
    click Logger "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/utils/logger.py"
    click Exceptions "https://github.com/ao-chii/nextranslation/blob/main/src/nex_translation/utils/exceptions.py"
    click ConfigFile "https://github.com/ao-chii/nextranslation/blob/main/config.json"
    click BuildFile "https://github.com/ao-chii/nextranslation/blob/main/pyproject.toml"
    click DocsLayers1 "https://github.com/ao-chii/nextranslation/blob/main/docs/LayeredAchitecture.md"
    click DocsLayers2 "https://github.com/ao-chii/nextranslation/blob/main/docs/layer_architecture.md"
    click DocsOverview "https://github.com/ao-chii/nextranslation/blob/main/docs/ProjectOverview.md"
    click DocsReqs "https://github.com/ao-chii/nextranslation/blob/main/docs/Requirements.md"

    %% Styles
    classDef presentation fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef core fill:#a2c8f5,stroke:#333,stroke-width:1px
    classDef infra fill:#f5cda2,stroke:#333,stroke-width:1px
    classDef utils fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef external fill:#ffe680,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
