# kaii-lb/overskride architecture

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

- Interactive diagram: https://gitdiagram.com/kaii-lb/overskride
- Repository: https://github.com/kaii-lb/overskride

## Overview

##### Project type and purpose
- Type: Native desktop application written in Rust with a GTK4/libadwaita UI.
- Purpose: A GUI Bluetooth & OBEX client (device enumeration, pairing, file transfer) that is DE/WM-agnostic and packaged via Flatpak.

##### File structure
- Top-level build: Cargo.toml (Rust), meson.build (Meson/Ninja), Flatpak build scripts (build-flatpak.sh, make-pkg.sh).
- src/: application.rs & main.rs (entry), modules:
– bluetooth/: D-Bus wrappers & business logic for BlueZ (agent, profiles, battery, services).
– obex/: OBEX client implementation.
– gtk/: .blp UI templates & CSS for views.
– widgets/: custom GTK widget code (battery indicator, device rows, popovers).
– config.rs: settings management (glib-schemas XML).
– window.rs: top-level window orchestration.
- assets/: static images (splash/screenshots).
- po/: localization support.
- subprojects/: wrap for third-party code (e.g., blueprint-compiler).

##### Extract insights from README
- Uses systemd-enabled Bluetooth daemon (BlueZ).
- Built & run via Meson + glib-compile-schemas + Flatpak.
- Core features: device listing, pairing/authentication, file send/receive, adapter management, battery & audio profiles.

##### Core components
a. Frontend (UI Layer)
– GTK4/libadwaita widgets & views (.blp files + CSS)
– Window manager: application.rs → window.rs
b. Backend (Logic Layer)
– Bluetooth Manager (src/bluetooth/*)
– OBEX Client (src/obex/*)
– Configuration Service (src/config.rs + gschema.xml)
c. Data & Storage
– Local user settings (dconf/GLib settings)
– File transfer storage location
d. External Services
– BlueZ D-Bus API (org.bluez)
– systemd (bluetooth.service)
– Flatpak runtime (org.gnome.Platform)
e. Build & Packaging
– Meson build system & Ninja
– Cargo for Rust crates
– Flatpak bundling

##### Relationships & interactions
- UI Layer emits user events → Logic Layer
- Bluetooth Manager ↔ BlueZ via D-Bus (pair, connect, battery polling)
- OBEX Client ↔ BlueZ’s obexd or direct OBEX channel
- Logic Layer updates UI via signals (GLib main loop)
- Config Service ⇄ dconf/GSettings backend
- File I/O: Logic stores incoming files under configured directory
- Localization: po/ files → gettext
- Build Flow: Meson calls Cargo, processes data/, compiles glib-schemas, packs Flatpak

##### Architectural patterns & principles
- Event-driven (GLib main loop dispatch)
- Modular separation: UI vs. business logic vs. protocol layers
- MVC-style: widgets/views (View), bluetooth/obex modules (Model/Controller)
- Single-process, asynchronous calls to D-Bus

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend UI Layer"
        BI["battery-indicator.blp"]:::ui
        CSR["connected-switch-row.blp"]:::ui
        DAR["device-action-row.blp"]:::ui
        HO["help-overlay.blp"]:::ui
        MIP["more-info-page.blp"]:::ui
        PPP["preferences-page.blp"]:::ui
        RPO["receiving-popover.blp"]:::ui
        RR["receiving-row.blp"]:::ui
        SR["selectable-row.blp"]:::ui
        SEM["startup-error-message.blp"]:::ui
        WBLA["window.blp"]:::ui
        CSS["style.css"]:::ui

        subgraph "Window Manager"
            MAIN["main.rs"]:::ui
            APP["application.rs"]:::ui
            WIN["window.rs"]:::ui
        end
    end

    subgraph "Logic Layer"
        subgraph "Bluetooth Manager"
            AG["agent.rs"]:::logic
            AP["audio_profiles.rs"]:::logic
            BATM["battery.rs"]:::logic
            BS["bluetooth_settings.rs"]:::logic
            DEV["device.rs"]:::logic
            MSG["message.rs"]:::logic
            SVC["services.rs"]:::logic
        end
        subgraph "OBEX Client"
            OBX["obex.rs"]:::logic
            OBU["obex_utils.rs"]:::logic
        end
        CFG["config.rs"]:::logic
        CRS["config.rs.in"]:::logic
        GRSC["overskride.gresource.xml"]:::logic
    end

    subgraph "Data & Storage"
        GS["io.github.kaii_lb.Overskride.gschema.xml"]:::data
        SETTINGS["dconf/GSettings"]:::data
        STORAGE["File Storage Location"]:::data
    end

    subgraph "External Services"
        BLUEZ["BlueZ D-Bus API"]:::ext
        OBEXD["OBEX Daemon"]:::ext
        SYSTEMD["systemd bluetooth.service"]:::ext
        FLATPAKRT["Flatpak Runtime"]:::ext
    end

    subgraph "Build & Packaging"
        CT["Cargo.toml"]:::build
        MB["meson.build"]:::build
        SMB["src/meson.build"]:::build
        DMB["data/meson.build"]:::build
        BFP["build-flatpak.sh"]:::build
        MPKG["make-pkg.sh"]:::build
        DESKTOP["io.github.kaii_lb.Overskride.desktop.in"]:::build
        APPDATA["io.github.kaii_lb.Overskride.appdata.xml.in"]:::build
        ICONS["data/icons/…"]:::build
        MANIFEST["io.github.kaii_lb.Overskride.json"]:::build
    end

    %% Connections
    BI -->|"user action"| AG
    CSR -->|"user action"| AG
    DAR -->|"user action"| AG
    WBLA -->|"user action"| AG
    MAIN -->|"initializes"| APP
    APP -->|"creates"| WIN
    WIN -->|"renders"| WBLA

    APP -->|"invokes"| CFG
    APP -->|"invokes"| AG
    APP -->|"invokes"| OBX

    AG -->|"D-Bus"| BLUEZ
    OBX -->|"OBEX"| OBEXD
    CFG -->|"reads/writes"| SETTINGS
    GS -->|"compile-schemas"| CFG

    AG -->|"signals"| WIN
    OBX -->|"file I/O"| STORAGE

    SYSTEMD -->|"provides"| BLUEZ
    MANIFEST -->|"bundles with"| FLATPAKRT

    MB -->|"includes"| CT
    MB -->|"includes"| SMB
    MB -->|"includes"| DMB
    CT -->|"cargo build"| BFP
    MB -->|"runs"| BFP
    BFP -->|"produces"| MANIFEST
    MPKG -->|"packages"| MANIFEST

    %% Click Events
    click BI "https://github.com/kaii-lb/overskride/blob/main/src/gtk/battery-indicator.blp"
    click CSR "https://github.com/kaii-lb/overskride/blob/main/src/gtk/connected-switch-row.blp"
    click DAR "https://github.com/kaii-lb/overskride/blob/main/src/gtk/device-action-row.blp"
    click HO "https://github.com/kaii-lb/overskride/blob/main/src/gtk/help-overlay.blp"
    click MIP "https://github.com/kaii-lb/overskride/blob/main/src/gtk/more-info-page.blp"
    click PPP "https://github.com/kaii-lb/overskride/blob/main/src/gtk/preferences-page.blp"
    click RPO "https://github.com/kaii-lb/overskride/blob/main/src/gtk/receiving-popover.blp"
    click RR "https://github.com/kaii-lb/overskride/blob/main/src/gtk/receiving-row.blp"
    click SR "https://github.com/kaii-lb/overskride/blob/main/src/gtk/selectable-row.blp"
    click SEM "https://github.com/kaii-lb/overskride/blob/main/src/gtk/startup-error-message.blp"
    click WBLA "https://github.com/kaii-lb/overskride/blob/main/src/gtk/window.blp"
    click CSS "https://github.com/kaii-lb/overskride/blob/main/src/gtk/style.css"

    click MAIN "https://github.com/kaii-lb/overskride/blob/main/src/main.rs"
    click APP "https://github.com/kaii-lb/overskride/blob/main/src/application.rs"
    click WIN "https://github.com/kaii-lb/overskride/blob/main/src/window.rs"

    click AG "https://github.com/kaii-lb/overskride/blob/main/src/bluetooth/agent.rs"
    click AP "https://github.com/kaii-lb/overskride/blob/main/src/bluetooth/audio_profiles.rs"
    click BATM "https://github.com/kaii-lb/overskride/blob/main/src/bluetooth/battery.rs"
    click BS "https://github.com/kaii-lb/overskride/blob/main/src/bluetooth/bluetooth_settings.rs"
    click DEV "https://github.com/kaii-lb/overskride/blob/main/src/bluetooth/device.rs"
    click MSG "https://github.com/kaii-lb/overskride/blob/main/src/bluetooth/message.rs"
    click SVC "https://github.com/kaii-lb/overskride/blob/main/src/bluetooth/services.rs"

    click OBX "https://github.com/kaii-lb/overskride/blob/main/src/obex/obex.rs"
    click OBU "https://github.com/kaii-lb/overskride/blob/main/src/obex/obex_utils.rs"

    click CFG "https://github.com/kaii-lb/overskride/blob/main/src/config.rs"
    click CRS "https://github.com/kaii-lb/overskride/blob/main/src/config.rs.in"
    click GS "https://github.com/kaii-lb/overskride/blob/main/data/io.github.kaii_lb.Overskride.gschema.xml"

    click GRSC "https://github.com/kaii-lb/overskride/blob/main/src/overskride.gresource.xml"

    click CT "https://github.com/kaii-lb/overskride/blob/main/Cargo.toml"
    click MB "https://github.com/kaii-lb/overskride/blob/main/meson.build"
    click SMB "https://github.com/kaii-lb/overskride/blob/main/src/meson.build"
    click DMB "https://github.com/kaii-lb/overskride/blob/main/data/meson.build"
    click BFP "https://github.com/kaii-lb/overskride/blob/main/build-flatpak.sh"
    click MPKG "https://github.com/kaii-lb/overskride/blob/main/make-pkg.sh"
    click DESKTOP "https://github.com/kaii-lb/overskride/blob/main/data/io.github.kaii_lb.Overskride.desktop.in"
    click APPDATA "https://github.com/kaii-lb/overskride/blob/main/data/io.github.kaii_lb.Overskride.appdata.xml.in"
    click ICONS "https://github.com/kaii-lb/overskride/tree/main/data/icons/"
    click MANIFEST "https://github.com/kaii-lb/overskride/blob/main/io.github.kaii_lb.Overskride.json"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1F618D,color:#1F618D;
    classDef logic fill:#ABEBC6,stroke:#196F3D,color:#196F3D;
    classDef data fill:#F9E79F,stroke:#B9770E,color:#B9770E;
    classDef ext fill:#F5CBA7,stroke:#A04000,color:#A04000;
    classDef build fill:#D7BDE2,stroke:#512E5F,color:#512E5F;
```
