# mrstarkng/hedwig-translation-plugin architecture

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

- Interactive diagram: https://gitdiagram.com/mrstarkng/hedwig-translation-plugin
- Repository: https://github.com/mrstarkng/hedwig-translation-plugin

## Overview

##### Project Type & Purpose
- The project is a full-stack plugin that integrates directly into Google Docs for document translation.
- The frontend (built with Google Apps Script) provides a Sidebar UI for user interactions.
- The backend (a Python Flask application) handles translation requests (using asynchronous handling for long documents), language detection, and even PDF utilities.
- It integrates with an external Translation API (Google Gemini) which is core to its translation capability.

##### File Structure Insights
- The “appsscript” folder contains Google Apps Script files like Code.gs, Sidebar.html, and configuration (appsscript.json) that define the UI and interaction logic within Google Docs.
- The “client” folder, though seeming a bit redundant, appears to hold additional client-side code (app.js, app.py, code.gs, index.html, etc.) possibly for testing, prototyping, or alternative client integrations.
- The “server” folder holds the Python backend (app.py, pdf_utils.py, and test scripts) alongside font/model files (e.g., several NotoSans-related files) needed for rendering or processing documents.

##### Main Components
a. Google Docs Integration Frontend:
– This component interfaces directly within Google Docs.
– Include a note about the configuration file (appsscript.json) that governs deployment.
b. Client/Test Interface:
– Represent the “client” directory as an auxiliary client application that might simulate or test integration with the backend.
c. Backend Server:
– Include subcomponents: asynchronous processing (aiohttp, asyncio for handling long text), translation request handling, and utilities (pdf_utils.py).
– Also denote testing utilities (test_translation.py) as part of internal tests.
d. External Services:
– Indicate future expansion with placeholders for additional models (such as GPT-4).
e. Development Tools:
– Optionally, include a small note for “ngrok” that is used for tunneling the backend so that it can securely communicate with the Apps Script frontend.

##### Relationships & Data Flow
- Optionally, represent the “Client” component interacting with the server if it’s used for demo/testing purposes.

##### Architectural Patterns & Technologies
- Clear separation between frontend and backend, which is a standard full-stack design.
- Asynchronous processing in the backend, which handles splitting and concurrent translation for long texts.
- That the frontend uses Google Apps Script leveraging HTML/CSS/JS, while the backend uses Python technologies (Flask, aiohttp, asyncio).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User in Google Docs"]

    %% Frontend: Google Docs Integration
    subgraph "Google Docs Integration Frontend"
        UI["Google Apps Script UI (Sidebar)"]:::frontend
        Config["Configuration (appsscript.json)"]:::frontend
    end

    %% Backend: Python Server
    subgraph "Python Backend Server"
        Backend["Python Flask Server"]:::backend
        Async["Asynchronous Processing"]:::backend
        PDF["PDF Utilities (pdf_utils.py)"]:::backend
        Test["Test Utilities (test_translation.py)"]:::backend
    end

    %% External Service
    Gemini["Google Gemini API"]:::external

    %% Client/Test Interface
    Client["Client/Test Interface"]:::client

    %% Connections and Data Flows
    User -->|"UserInteraction"| UI
    UI -->|"TranslationRequest(via_ngrok)"| Backend
    Backend -->|"APITranslationRequest"| Gemini
    Gemini -->|"APITranslationResponse"| Backend
    Backend -->|"ReturnTranslatedText"| UI
    Client -->|"TestRequest"| Backend

    %% Click Events for Component Mapping
    click UI "https://github.com/mrstarkng/hedwig-translation-plugin/blob/main/appsscript/Code.gs"
    click Config "https://github.com/mrstarkng/hedwig-translation-plugin/blob/main/appsscript/appsscript.json"
    click Client "https://github.com/mrstarkng/hedwig-translation-plugin/tree/main/client/"
    click Backend "https://github.com/mrstarkng/hedwig-translation-plugin/blob/main/server/app.py"
    click PDF "https://github.com/mrstarkng/hedwig-translation-plugin/blob/main/server/pdf_utils.py"
    click Test "https://github.com/mrstarkng/hedwig-translation-plugin/blob/main/server/test_translation.py"

    %% Styling Classes
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef external fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef client fill:#f4a460,stroke:#000,stroke-width:2px;
```
