# lacalud/gui_converter architecture

> Architecture diagram of the GitHub repository lacalud/gui_converter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lacalud/gui_converter
- Repository: https://github.com/lacalud/gui_converter

## Overview

##### What this project is (type + purpose)
This repo is a **Python desktop GUI application** (“GUI Converter”) that lets a user:
- upload/select files (docs/images/audio/video),
- auto-detect input format,
- preview content,
- choose an output format,
- convert and “Save as” (explicitly mentioned for pictures).

Architecturally it’s a **single-process, monolithic GUI app** with a small internal module structure:
- `main.py` boots the app,
- `ui/` implements the GUI and GUI-driven conversion logic,
- `tests/` provides unit tests (notably around `ui/main_tab.py`),
- toolchain/config is via `pyproject.toml` (Poetry), `requirements.txt` (pip), and CI in `.github/workflows/test.yml`.

##### How to read the file tree into architectural components
From the tree:

##### Entry / Composition Root
- `main.py`: **application entrypoint** and likely the place where the GUI framework is initialized and the main window/tab is mounted.

##### Quality / Verification
- `tests/main_tab_tests.py`: indicates the main tab logic is unit-tested; include **test harness** as a non-runtime but important lifecycle component.

##### User
- interacts with GUI (select file, choose output format, preview, convert, save).

##### Desktop GUI Application (Python)
- **`main.py` (Bootstrap/App Runner)**
Initializes GUI framework, creates main window, mounts `MainTab`.
- **`ui.main_tab.MainTab` (UI Controller/Presenter)**
Handles user events and orchestrates: file selection → validation → format detection → preview → conversion → save.
- **`ui.utils` (Domain/Service Helpers)**
Functions/classes that actually do: detect format, call converters, manage temp files, prepare preview data.
- **`ui.constants` (Configuration/Supported Formats)**
Defines supported input/output mappings; used by MainTab and utils.

##### Local File System
- Source files (input)
- Output files (converted)
- Temporary files (if preview/conversion needs them)

##### External Conversion/Preview Engines (Dependencies)
- “Image conversion library” (e.g., Pillow)
- “Audio conversion library” (e.g., pydub/ffmpeg wrapper)
- “Video conversion backend” (often ffmpeg)
- “Document conversion library” (docx/pdf tooling, etc.)

##### (Optional but recommended) Observability / Error Handling
- If there is logging or error dialogs, represent a small “Error handling / Logging” component (even if minimal today). The README TODO mentions improving error handling—diagramming it helps drive the roadmap.

##### Tests + CI lane (non-runtime)
- **Unit Tests (`tests/main_tab_tests.py`)** calling into `ui.main_tab` (and indirectly `ui.utils`)
- **GitHub Actions (`.github/workflows/test.yml`)** running tests on pushes/PRs

##### User → MainTab
- “Select/Upload File”
##### MainTab → File System
- Reads selected input file
##### MainTab → utils
- `detect_input_format(file_path)` (or equivalent)
##### MainTab → constants
- Look up allowed output formats for detected input type
##### User → MainTab
- “Choose output format”, “Preview”, “Convert”, “Save as”
##### MainTab → utils → Conversion Backends
- `convert(input_path, output_format, options)`
##### utils → File System
- Writes output file (and temp preview artifacts if needed)
##### MainTab → GUI
- Updates preview window, status, errors

##### Test/CI flow (separate lane)
- `main_tab_tests.py` → imports/calls → `ui/main_tab.py` (+ `ui/utils.py`)
- GitHub Actions runner → executes → test suite → produces pass/fail signal

##### Architectural patterns to highlight (based on structure)
This repo strongly suggests:
- **UI-controller + helper-services** pattern:
- `main_tab.py` orchestrates
- `utils.py` does heavy lifting
- `constants.py` constrains supported formats/options
- **Single-process monolith** (no backend server, no network API)
- **Dependency-driven conversion** (real conversion work likely delegated to libraries or system tools)

- `main_tab` depends on `utils` + `constants`
- `utils` depends on “Conversion Backends” + “File System”

##### High-level (Context/Container)
- User
- GUI Converter App
- Local File System
- External conversion libraries/tools
- CI/Test lane (optional but useful)

##### Component-level (inside GUI Converter App)
- `main.py` bootstrap
- `ui.main_tab` (event handlers + orchestration)
- `ui.utils` (format detection, conversion, preview helpers)
- `ui.constants` (supported formats/config)

##### Make “format detection → output options → conversion → save” explicit
- Format Detector
- Preview Generator
- Converter
- Save/Export Handler

Even if they are functions today, drawing them as components is beneficial; it clarifies responsibilities and makes future refactors (batch conversion, CLI) straightforward.

- “CLI Wrapper” (future) reusing the same `utils` conversion services
- “Drag & Drop” input path into MainTab
- “Batch conversion” queue/worker inside app (still single-process, but asynchronous)

##### Labels
- Use actual module names from tree:
- `main.py`
- `ui/main_tab.py`
- `ui/utils.py`
- `ui/constants.py`
- `tests/main_tab_tests.py`
- Name the UI surface as “Main Tab / Preview Window” since README emphasizes preview.

- `MainTab → utils: convert()`
- `utils → File System: write output`
- `tests → ui.main_tab`
- `GitHub Actions → pytest (or test runner)`

To avoid guessing, quickly inspect:
- `requirements.txt` / `pyproject.toml` to enumerate conversion/preview dependencies (and whether `ffmpeg` is required).
- `ui/main_tab.py` to confirm:
- how files are selected (file dialog vs drag-drop),
- whether conversion is synchronous or threaded,
- where preview is generated (direct rendering vs temp files),
- error-handling paths.
- `ui/utils.py` to identify true “service” boundaries (format detection vs conversion vs preview).

- User ↔ GUI Converter App ↔ File System
- GUI Converter App → Conversion Backends (libraries/tools)
- (Optional) CI lane: GitHub Actions → Tests

- `main.py` → `MainTab`
- `MainTab` → `constants`
- `MainTab` → `utils`
- `utils` → Conversion Backends
- `utils` → File System

This level of separation is “detailed without overthinking”: it splits the project into the maximum meaningful components implied by the repo, while staying faithful to what actually exists.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External Actors / Systems
    %% =========================
    User["User"]:::external
    FS[("Local File System\n- Input files\n- Output files\n- Temp/preview artifacts")]:::storage
    Backends["Conversion Backends\n(Python libs / system tools)\n(see pyproject/requirements)"]:::external
    SysTools["System Tools (optional)\n(e.g., ffmpeg)"]:::external

    %% =========================
    %% Container: Desktop App
    %% =========================
    subgraph "GUI Converter (Python Desktop GUI App)"
        direction TB

        MainPy["main.py\nBootstrap / App Runner"]:::app
        MainTab["ui.main_tab.MainTab\nUI Controller / Presenter\n(Main Tab / Preview Window)"]:::app
        Constants["ui.constants\nSupported Formats / UI Constants"]:::app

        subgraph "ui.utils (Helper Services)"
            direction TB
            Utils["ui.utils\nService Facade"]:::service
            Detect["Format Detection"]:::service
            Preview["Preview Generator"]:::service
            Convert["Converter / Transcoder"]:::service
            Export["Save As / Export Handler"]:::service
        end

        ErrorLog["Error Handling / Logging\n(status + dialogs)"]:::support

        %% Future/roadmap extension points (dashed)
        FutureCLI["Future: CLI Wrapper\n(reuse utils)"]:::future
        FutureDnD["Future: Drag & Drop Input"]:::future
        FutureBatch["Future: Batch Conversion Queue/Worker"]:::future
    end

    %% =========================
    %% Runtime Data Flow
    %% =========================
    User -->|"select_file"| MainTab
    MainPy -->|"mount_main_window"| MainTab

    MainTab -->|"read_input"| FS
    MainTab -->|"detect_input_format()"| Detect
    Detect -->|"uses"| Constants
    MainTab -->|"get_output_options"| Constants

    User -->|"choose_format_preview_convert_save"| MainTab
    MainTab -->|"generate_preview()"| Preview
    Preview -->|"read/write_temp"| FS

    MainTab -->|"convert(input,output)"| Convert
    Convert -->|"calls"| Backends
    Backends -.->|"may_require"| SysTools

    Convert -->|"write_output"| FS
    MainTab -->|"save_as"| Export
    Export -->|"write_output"| FS

    MainTab -->|"show_errors/status"| ErrorLog

    %% =========================
    %% Tests + CI (non-runtime lane)
    %% =========================
    subgraph "Quality Lane (CI + Tests)"
        direction TB
        GHA["GitHub Actions\nCI Workflow"]:::ci
        Tests["Unit Tests\n(tests/main_tab_tests.py)"]:::ci
        TestInit["tests package init\n(tests/__init__.py)"]:::ci
        PyProject["pyproject.toml\nPoetry config"]:::config
        ReqTxt["requirements.txt\npip dependencies"]:::config
    end

    GHA -.->|"runs"| Tests
    Tests -.->|"imports"| TestInit
    Tests -.->|"tests"| MainTab
    Tests -.->|"calls"| Utils

    PyProject -.->|"declares_deps_for"| Backends
    ReqTxt -.->|"declares_deps_for"| Backends
    GHA -.->|"installs_deps"| PyProject
    GHA -.->|"installs_deps"| ReqTxt

    %% =========================
    %% Roadmap links (dashed)
    %% =========================
    FutureCLI -.->|"reuse"| Utils
    FutureDnD -.->|"triggers_select_file"| MainTab
    FutureBatch -.->|"enqueue_jobs_for"| Convert

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click MainPy "https://github.com/lacalud/gui_converter/blob/main/main.py"
    click MainTab "https://github.com/lacalud/gui_converter/blob/main/ui/main_tab.py"
    click Utils "https://github.com/lacalud/gui_converter/blob/main/ui/utils.py"
    click Constants "https://github.com/lacalud/gui_converter/blob/main/ui/constants.py"
    click Tests "https://github.com/lacalud/gui_converter/blob/main/tests/main_tab_tests.py"
    click TestInit "https://github.com/lacalud/gui_converter/blob/main/tests/__init__.py"
    click GHA "https://github.com/lacalud/gui_converter/blob/main/.github/workflows/test.yml"
    click PyProject "https://github.com/lacalud/gui_converter/blob/main/pyproject.toml"
    click ReqTxt "https://github.com/lacalud/gui_converter/blob/main/requirements.txt"

    %% =========================
    %% Styles
    %% =========================
    classDef app fill:#1f6feb,stroke:#0b3d91,color:#ffffff,stroke-width:1.5px
    classDef service fill:#3b82f6,stroke:#1e40af,color:#ffffff,stroke-width:1.2px
    classDef support fill:#2563eb,stroke:#1e3a8a,color:#ffffff,stroke-width:1.2px
    classDef storage fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1.5px
    classDef external fill:#f59e0b,stroke:#b45309,color:#111827,stroke-width:1.5px
    classDef ci fill:#22c55e,stroke:#166534,color:#052e16,stroke-width:1.5px
    classDef config fill:#86efac,stroke:#166534,color:#052e16,stroke-width:1.2px
    classDef future fill:#ffffff,stroke:#64748b,color:#0f172a,stroke-dasharray:6 4,stroke-width:1.2px
```
