How lacalud/gui_converter works
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.