# mijorus/gearlever architecture

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

- Interactive diagram: https://gitdiagram.com/mijorus/gearlever
- Repository: https://github.com/mijorus/gearlever

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interfaces"
        GW["GearleverWindow.py"]:::internal
        WS["WelcomeScreen.py"]:::internal
        AD["AppDetails.py"]:::internal
        IA["InstalledAppsList.py"]:::internal
        COMPS["components/"]:::internal
        UIF["gtk UI files (src/gtk/)"]:::internal
        CLI["Cli.py"]:::internal
    end

    subgraph "Core Engine"
        State["State"]:::internal
        Fetcher["BackgroundUpdatesFetcher"]:::internal
        MultiInst["MultiInstall"]:::internal
        MultiUpd["MultiUpdate"]:::internal
    end

    subgraph "Model Layer"
        ALE["AppListElement"]:::internal
        ALS["AppsListSection"]:::internal
        UM["UpdateManager"]:::internal
        M["Models"]:::internal
    end

    subgraph "Providers & Services"
        AIP["AppImageProvider"]:::internal
        PL["providers_list.py"]:::internal
        DBus["Flatpak D-Bus"]:::external
    end

    subgraph "Persistence & Configuration"
        JSONCFG["json_config.py"]:::persistence
        GSET["gearlever.gschema.xml"]:::persistence
    end

    subgraph "Asset Bundle"
        GRES["gearlever.gresource.xml"]:::persistence
        CSS["style.css"]:::persistence
        DEMO["demo.AppImage"]:::persistence
        ICONS["data/icons/"]:::persistence
    end

    subgraph "External Systems"
        FS["Local File System"]:::external
    end

    %% UI -> Core
    GW -->|"invoke"| State
    WS -->|"invoke"| State
    AD -->|"invoke"| State
    IA -->|"invoke"| State
    CLI -->|"execute_command()"| State

    %% Core -> Models
    State -->|"update_state()"| ALE
    State -->|"update_state()"| ALS
    Fetcher -->|"fetch_updates()"| UM
    MultiInst -->|"install_apps()"| ALE
    MultiUpd -->|"update_apps()"| ALE

    %% Core -> Providers
    State -->|"delegate()"| AIP
    Fetcher -->|"delegate()"| AIP

    %% Providers -> External & DBus
    AIP -->|"install_appimage()"| FS
    AIP -->|"refresh_menu()"| DBus

    %% Core <-> Persistence
    State -->|"load_config() / save_config()"| JSONCFG
    State -->|"read_schema() / write_schema()"| GSET

    %% Asset Bundle -> UI & Core
    GRES -->|"load_resources()"| GW
    CSS -->|"apply_style()"| GW
    UIF -->|"load_ui()"| GW
    DEMO -->|"sample()"| State
    ICONS -->|"load_icons()"| GW

    %% Click Events
    click GW "https://github.com/mijorus/gearlever/blob/master/src/GearleverWindow.py"
    click WS "https://github.com/mijorus/gearlever/blob/master/src/WelcomeScreen.py"
    click AD "https://github.com/mijorus/gearlever/blob/master/src/AppDetails.py"
    click IA "https://github.com/mijorus/gearlever/blob/master/src/InstalledAppsList.py"
    click COMPS "https://github.com/mijorus/gearlever/tree/master/src/components/"
    click UIF "https://github.com/mijorus/gearlever/tree/master/src/gtk/"
    click CLI "https://github.com/mijorus/gearlever/blob/master/src/Cli.py"
    click State "https://github.com/mijorus/gearlever/blob/master/src/State.py"
    click Fetcher "https://github.com/mijorus/gearlever/blob/master/src/BackgroudUpdatesFetcher.py"
    click MultiInst "https://github.com/mijorus/gearlever/blob/master/src/MultiInstall.py"
    click MultiUpd "https://github.com/mijorus/gearlever/blob/master/src/MultiUpdate.py"
    click ALE "https://github.com/mijorus/gearlever/blob/master/src/models/AppListElement.py"
    click ALS "https://github.com/mijorus/gearlever/blob/master/src/models/AppsListSection.py"
    click UM "https://github.com/mijorus/gearlever/blob/master/src/models/UpdateManager.py"
    click M "https://github.com/mijorus/gearlever/blob/master/src/models/Models.py"
    click AIP "https://github.com/mijorus/gearlever/blob/master/src/providers/AppImageProvider.py"
    click PL "https://github.com/mijorus/gearlever/blob/master/src/providers/providers_list.py"
    click JSONCFG "https://github.com/mijorus/gearlever/blob/master/src/lib/json_config.py"
    click GSET "https://github.com/mijorus/gearlever/blob/master/data/it.mijorus.gearlever.gschema.xml"
    click GRES "https://github.com/mijorus/gearlever/blob/master/src/gearlever.gresource.xml"
    click CSS "https://github.com/mijorus/gearlever/blob/master/src/assets/style.css"
    click DEMO "https://github.com/mijorus/gearlever/blob/master/src/assets/demo.AppImage"
    click ICONS "https://github.com/mijorus/gearlever/tree/master/data/icons/"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef persistence fill:#E8F5D0,stroke:#228B22,stroke-width:1px
    classDef external fill:#F5D0D0,stroke:#B22222,stroke-width:1px,stroke-dasharray: 5 5
```
