How mijorus/gearlever works
Project type and purpose
• This is a desktop application written in Python, using GTK for its graphical UI and also exposing a CLI interface.
• It manages AppImage files: integration into the system menu, updates, removal, and keeps a local folder of AppImages.
• It is built and distributed as a Flatpak application, using Meson as its build system and GResource for bundling assets.
File structure
• Top-level build files and config
– meson.build, python3-requirements.json, requirements.txt, the Flatpak manifest (it.mijorus.gearlever.json), build-aux scripts.
• Data & assets
• Source code
– src/main.py: application entry point.
– src/Cli.py: command-line interface module.
– src/GearleverWindow.py, WelcomeScreen.py, AppDetails.py, InstalledAppsList.py: the main GTK windows and screens.
– src/components/: reusable GTK widgets and dialogs.
– src/models/: business-logic models (AppsListSection, UpdateManager, etc.).
– src/providers/: abstraction over AppImage operations (AppImageProvider).
– src/lib/: utility modules (async helpers, JSON config, terminal integration, secrets, etc.).
– src/assets/: static resources (demo AppImage, style.css).
– src/gtk/: UI definitions in .ui files for Glade/GtkBuilder.
• Tests
– tests/test_cli.py covers basic CLI behaviors.
Key architectural patterns and layers
• Layered MVC-style separation
– View layer: src/gtk/*.ui, GearleverWindow and component classes.
– Model layer: src/models handles data structures and update logic.
– Controller/Service layer: Cli.py and background fetchers orchestrate actions.
• Provider pattern
– src/providers/AppImageProvider encapsulates file operations, metadata generation, integration with Flatpak DBus API.
• Resource bundling
Main components
1. User Interfaces
– GUI (GTK Frontend)
– CLI module (command-line interface)
2. Core Engine
– Controllers: Main application logic (State, BackgroundUpdatesFetcher, MultiInstall/MultiUpdate)
– Model objects (AppsListSection, UpdateManager, AppListElement)
3. Providers & Services
– AppImageProvider (file integration, updating, removal)
– Flatpak DBus service (org.freedesktop.Flatpak)
4. Persistence & Configuration
– JSON config files (managed by json_config.py)
– GSettings schema (gearlever.gschema.xml)
5. Asset Bundle
6. External systems
– Local file system (AppImage storage folder)
– System menu / desktop database (via Flatpak permission and DBus)
Relationships and data flows
• GUI and CLI both invoke the Core Engine APIs (Controller layer).
• Core Engine calls Model objects to manage state and generate tasks.
• Core Engine delegates file and system integration to AppImageProvider.
• AppImageProvider communicates over DBus to the Flatpak service for menu refresh and sandboxed execution.
• Configuration utilities read/write JSON and GSettings.
• Asset bundle is loaded at startup into the ResourceManager and served to the UI.