# xtremethn/lift architecture

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

- Interactive diagram: https://gitdiagram.com/xtremethn/lift
- Repository: https://github.com/xtremethn/lift

## Overview

1. **What this repo is**
   Lift is a **Rust/GTK4/libadwaita desktop application** that ports NXLoader. Its purpose is to help a user send ROMs to a Nintendo Switch over **USB or wireless**. The architecture is centered around a GUI frontend plus transfer backends.

2. **Top-level application boundary**
   `src/main.rs` and `src/application.rs` likely form the startup layer: initialize GTK/libadwaita, load resources, wire application actions, and present the main window. The app is packaged as a desktop app with a GNOME-style UI and system integration artifacts in `data/`.

3. **UI subsystem**
   The `src/ui/` tree contains the whole interface:
   - `window.rs` / `window.blp`: main shell and navigation
   - `home_page.rs`, `roms_page/`, `settings.rs`, `rom.rs`: feature pages and per-ROM UI
   - `circular_progress_paintable.rs`: custom progress rendering for transfers
   The `.blp` files indicate GTK Blueprint templates; the UI is mostly declarative with Rust code-behind.

4. **State and model layer**
   `src/rom_data.rs`, `src/config.rs.in`, `src/utils.rs`, and `src/finder.rs` are the non-UI support layer:
   - ROM metadata and selection state
   - persistent configuration/settings
   - utility functions shared across subsystems
   - ROM discovery / file picking / search logic
   This is the data bridge between the UI and the transfer backends.

5. **Transfer workflow**
   The most important flow is:
   **user selects a ROM in the UI → app resolves ROM data → backend opens a transfer session → progress/status is reported back to the UI**.
   The progress indicator and separate ROM pages suggest transfers are long-running and asynchronous, with UI updates driven by backend state.

6. **USB backend**
   `src/usb/` is the USB transport subsystem. It is split into:
   - `manager/`: device access abstraction
   - `manager/gudev.rs`: native Linux device discovery
   - `manager/portal.rs`: Flatpak/portal-based USB access
   - `async_protocol.rs`: async data exchange protocol
   - `daemon.rs`: transfer-side service/process coordination
   `src/usb/mod.rs` ties these pieces together. This is the key boundary for local device I/O.

7. **USB access modes and packaging impact**
   The README and file tree show an architectural split between **native Linux** and **Flatpak**:
   - Native builds can use `libgudev` and `libusb`
   - Flatpak builds use desktop portals for USB permission/access
   This matters because USB device enumeration and permission handling are abstracted behind the manager layer, not scattered through the UI.

8. **Wireless / remote subsystem**
   `src/remote/` provides the non-USB transfer path:
   - `server.rs`
   - `reader.rs`
   - `mod.rs`
   The presence of both “server” and “reader” implies a self-contained protocol implementation for wireless sessions, separate from USB. In the architecture diagram this should appear as a peer transport backend alongside USB.

9. **ROMs page sub-flow**
   `src/ui/roms_page/` is a feature cluster with dedicated submodules:
   - `page.rs`: page orchestration
   - `usb.rs`: USB-specific ROM transfer UI
   - `net.rs`: network/wireless transfer UI
   This is a good place to draw a boundary between **selection/browsing** and **transport execution**: the page decides which backend path the user is using.

10. **Resources, styling, and desktop integration**
   `src/lift.gresource.xml`, `src/style.css`, and the files under `data/` show standard GNOME app packaging:
   - compiled UI/resources bundled into the binary
   - CSS styling for the widgets
   - desktop entry, appstream metadata, GSettings schema, and a systemd/DBus-style service file
   These are supporting infrastructure, not core logic, but they explain how the app is distributed and configured.

11. **Build and localization**
   The project uses **Cargo** plus **Meson** integration, with Nix support via `flake.nix`. `po/` contains translations, so the UI is localized. For an architecture diagram, these are outer build/deployment concerns rather than runtime subsystems.

12. **How to draw the main runtime boundaries**
   A clear diagram would show:
   - **GTK app shell** at the center
   - **UI pages** on top
   - **state/model layer** beneath UI
   - two **transport backends**: USB and wireless/remote
   - within USB, a split between **device discovery/access** and **async protocol/daemon**
   - external dependencies: **system USB stack / gudev / libusb / portal / GNOME desktop services**
   This captures the repo’s real separation of concerns: UI, model/state, and transport are distinct layers.

Main entry points: [`src/ui/roms_page/page.rs`](https://github.com/xtremethn/lift/blob/main/src/ui/roms_page/page.rs) (ROMs), [`src/usb/mod.rs`](https://github.com/xtremethn/lift/blob/main/src/usb/mod.rs) (USB), [`src/application.rs`](https://github.com/xtremethn/lift/blob/main/src/application.rs) (App), [`src/remote/mod.rs`](https://github.com/xtremethn/lift/blob/main/src/remote/mod.rs) (Remote)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.rs]"]
  node_application["App<br/>[application.rs]"]
end

subgraph group_ui["UI"]
  node_window["Window<br/>shell<br/>[window.rs]"]
  node_home_page["Home<br/>page<br/>[home_page.rs]"]
  node_roms_page["ROMs<br/>page<br/>[page.rs]"]
  node_roms_usb_ui["USB Transfer<br/>page-part<br/>[usb.rs]"]
  node_roms_net_ui["Net Transfer<br/>page-part<br/>[net.rs]"]
  node_rom_view["ROM Card<br/>[rom.rs]"]
  node_settings["Settings<br/>page<br/>[settings.rs]"]
  node_progress(("Progress<br/>widget"))
end

subgraph group_model["State & Model"]
  node_rom_data["ROM Data<br/>model<br/>[rom_data.rs]"]
  node_config["Config<br/>settings-model<br/>[config.rs.in]"]
  node_finder["Finder<br/>discovery<br/>[finder.rs]"]
  node_utils["Utils<br/>support<br/>[utils.rs]"]
end

subgraph group_usb["USB Backend"]
  node_usb_mod["USB<br/>transport<br/>[mod.rs]"]
  node_usb_manager["Device Manager<br/>access-layer<br/>[mod.rs]"]
  node_gudev["gudev<br/>native-discovery<br/>[gudev.rs]"]
  node_portal["Portal<br/>flatpak-access<br/>[portal.rs]"]
  node_async_protocol["Async Proto<br/>protocol<br/>[async_protocol.rs]"]
  node_daemon["Daemon<br/>session-coord<br/>[daemon.rs]"]
end

subgraph group_remote["Wireless Backend"]
  node_remote_mod["Remote<br/>transport<br/>[mod.rs]"]
  node_remote_server["Server<br/>[server.rs]"]
  node_remote_reader["Reader<br/>[reader.rs]"]
end

subgraph group_packaging["Packaging & Resources"]
  node_resources["Resources<br/>bundle<br/>[lift.gresource.xml]"]
  node_style["Style<br/>css<br/>[style.css]"]
  node_desktop_meta["Desktop Data<br/>desktop-packaging<br/>[meson.build]"]
end

node_main -->|"starts"| node_application
node_application -->|"presents"| node_window
node_window -->|"contains"| node_home_page
node_window -->|"contains"| node_roms_page
node_window -->|"contains"| node_settings
node_roms_page -->|"uses"| node_rom_view
node_roms_page -->|"routes"| node_roms_usb_ui
node_roms_page -->|"routes"| node_roms_net_ui
node_roms_page -->|"consumes"| node_rom_data
node_roms_page -->|"discovers"| node_finder
node_rom_view -->|"shows"| node_progress
node_settings -->|"edits"| node_config
node_home_page -->|"summarizes"| node_rom_data
node_roms_usb_ui -->|"starts"| node_usb_mod
node_roms_net_ui -->|"starts"| node_remote_mod
node_usb_mod -->|"uses"| node_usb_manager
node_usb_manager -->|"native"| node_gudev
node_usb_manager -->|"sandboxed"| node_portal
node_usb_mod -->|"speaks"| node_async_protocol
node_usb_mod -->|"coordinates"| node_daemon
node_remote_mod -->|"serves"| node_remote_server
node_remote_mod -->|"parses"| node_remote_reader
node_application -->|"loads"| node_resources
node_application -->|"applies"| node_style
node_application -.->|"integrates"| node_desktop_meta
node_roms_page -.->|"reports"| node_usb_mod
node_roms_page -.->|"reports"| node_remote_mod
node_utils -.->|"supports"| node_finder
node_utils -.->|"supports"| node_usb_mod
node_utils -.->|"supports"| node_remote_mod
node_config -.->|"influences"| node_usb_manager

click node_main "https://github.com/xtremethn/lift/blob/main/src/main.rs"
click node_application "https://github.com/xtremethn/lift/blob/main/src/application.rs"
click node_window "https://github.com/xtremethn/lift/blob/main/src/ui/window.rs"
click node_home_page "https://github.com/xtremethn/lift/blob/main/src/ui/home_page.rs"
click node_roms_page "https://github.com/xtremethn/lift/blob/main/src/ui/roms_page/page.rs"
click node_roms_usb_ui "https://github.com/xtremethn/lift/blob/main/src/ui/roms_page/usb.rs"
click node_roms_net_ui "https://github.com/xtremethn/lift/blob/main/src/ui/roms_page/net.rs"
click node_rom_view "https://github.com/xtremethn/lift/blob/main/src/ui/rom.rs"
click node_settings "https://github.com/xtremethn/lift/blob/main/src/ui/settings.rs"
click node_progress "https://github.com/xtremethn/lift/blob/main/src/ui/circular_progress_paintable.rs"
click node_rom_data "https://github.com/xtremethn/lift/blob/main/src/rom_data.rs"
click node_config "https://github.com/xtremethn/lift/blob/main/src/config.rs.in"
click node_finder "https://github.com/xtremethn/lift/blob/main/src/finder.rs"
click node_utils "https://github.com/xtremethn/lift/blob/main/src/utils.rs"
click node_usb_mod "https://github.com/xtremethn/lift/blob/main/src/usb/mod.rs"
click node_usb_manager "https://github.com/xtremethn/lift/blob/main/src/usb/manager/mod.rs"
click node_gudev "https://github.com/xtremethn/lift/blob/main/src/usb/manager/gudev.rs"
click node_portal "https://github.com/xtremethn/lift/blob/main/src/usb/manager/portal.rs"
click node_async_protocol "https://github.com/xtremethn/lift/blob/main/src/usb/async_protocol.rs"
click node_daemon "https://github.com/xtremethn/lift/blob/main/src/usb/daemon.rs"
click node_remote_mod "https://github.com/xtremethn/lift/blob/main/src/remote/mod.rs"
click node_remote_server "https://github.com/xtremethn/lift/blob/main/src/remote/server.rs"
click node_remote_reader "https://github.com/xtremethn/lift/blob/main/src/remote/reader.rs"
click node_resources "https://github.com/xtremethn/lift/blob/main/src/lift.gresource.xml"
click node_style "https://github.com/xtremethn/lift/blob/main/src/style.css"
click node_desktop_meta "https://github.com/xtremethn/lift/blob/main/data/meson.build"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_application toneBlue
class node_window,node_home_page,node_roms_page,node_roms_usb_ui,node_roms_net_ui,node_rom_view,node_settings,node_progress toneAmber
class node_rom_data,node_config,node_finder,node_utils toneMint
class node_usb_mod,node_usb_manager,node_gudev,node_portal,node_async_protocol,node_daemon toneRose
class node_remote_mod,node_remote_server,node_remote_reader toneIndigo
class node_resources,node_style,node_desktop_meta toneTeal
```

## Components

### Runtime

Application startup and the main GTK/libadwaita shell.

- [Main](https://github.com/xtremethn/lift/blob/main/src/main.rs): entrypoint · Process entry that boots the application. · `src/main.rs`
- [App](https://github.com/xtremethn/lift/blob/main/src/application.rs): gtk-app · Initializes GTK/libadwaita and wires application actions. · `src/application.rs`

### UI

Declarative pages and code-behind for the desktop interface.

- [Window](https://github.com/xtremethn/lift/blob/main/src/ui/window.rs): shell · Top-level application window and navigation container. · `src/ui/window.rs`
- [Home](https://github.com/xtremethn/lift/blob/main/src/ui/home_page.rs): page · Landing page and primary app overview. · `src/ui/home_page.rs`
- [ROMs](https://github.com/xtremethn/lift/blob/main/src/ui/roms_page/page.rs): page · ROM browsing and transfer page controller. · `src/ui/roms_page/page.rs`
- [USB Transfer](https://github.com/xtremethn/lift/blob/main/src/ui/roms_page/usb.rs): page-part · USB-specific transfer UI and controls. · `src/ui/roms_page/usb.rs`
- [Net Transfer](https://github.com/xtremethn/lift/blob/main/src/ui/roms_page/net.rs): page-part · Wireless transfer UI and controls. · `src/ui/roms_page/net.rs`
- [ROM Card](https://github.com/xtremethn/lift/blob/main/src/ui/rom.rs): Per-ROM presentation and actions. · `src/ui/rom.rs`
- [Settings](https://github.com/xtremethn/lift/blob/main/src/ui/settings.rs): page · Application settings page. · `src/ui/settings.rs`
- [Progress](https://github.com/xtremethn/lift/blob/main/src/ui/circular_progress_paintable.rs): widget · Custom circular progress rendering for transfers. · `src/ui/circular_progress_paintable.rs`

### State & Model

Shared data, configuration, and discovery logic.

- [ROM Data](https://github.com/xtremethn/lift/blob/main/src/rom_data.rs): model · ROM metadata and selection state. · `src/rom_data.rs`
- [Config](https://github.com/xtremethn/lift/blob/main/src/config.rs.in): settings-model · Persistent application settings model. · `src/config.rs.in`
- [Finder](https://github.com/xtremethn/lift/blob/main/src/finder.rs): discovery · ROM discovery, file picking, and search logic. · `src/finder.rs`
- [Utils](https://github.com/xtremethn/lift/blob/main/src/utils.rs): support · Shared helpers used across subsystems. · `src/utils.rs`

### USB Backend

USB transport, device access, and session coordination.

- [USB](https://github.com/xtremethn/lift/blob/main/src/usb/mod.rs): transport · USB transport subsystem entry point. · `src/usb/mod.rs`
- [Device Manager](https://github.com/xtremethn/lift/blob/main/src/usb/manager/mod.rs): access-layer · Abstracts device discovery and access. · `src/usb/manager/mod.rs`
- [gudev](https://github.com/xtremethn/lift/blob/main/src/usb/manager/gudev.rs): native-discovery · Native Linux device discovery backend. · `src/usb/manager/gudev.rs`
- [Portal](https://github.com/xtremethn/lift/blob/main/src/usb/manager/portal.rs): flatpak-access · Portal-based USB access for sandboxed builds. · `src/usb/manager/portal.rs`
- [Async Proto](https://github.com/xtremethn/lift/blob/main/src/usb/async_protocol.rs): protocol · Async USB data exchange protocol. · `src/usb/async_protocol.rs`
- [Daemon](https://github.com/xtremethn/lift/blob/main/src/usb/daemon.rs): session-coord · Transfer-side service and process coordination. · `src/usb/daemon.rs`

### Wireless Backend

Network/remote transfer path for non-USB sessions.

- [Remote](https://github.com/xtremethn/lift/blob/main/src/remote/mod.rs): transport · Wireless transfer subsystem entry point. · `src/remote/mod.rs`
- [Server](https://github.com/xtremethn/lift/blob/main/src/remote/server.rs): server · Remote session server endpoint. · `src/remote/server.rs`
- [Reader](https://github.com/xtremethn/lift/blob/main/src/remote/reader.rs): protocol-reader · Reads remote transfer stream and payloads. · `src/remote/reader.rs`

### Packaging & Resources

Desktop integration, bundled resources, and styling.

- [Resources](https://github.com/xtremethn/lift/blob/main/src/lift.gresource.xml): bundle · Compiled UI resources and app assets. · `src/lift.gresource.xml`
- [Style](https://github.com/xtremethn/lift/blob/main/src/style.css): css · Global widget styling. · `src/style.css`
- [Desktop Data](https://github.com/xtremethn/lift/blob/main/data/meson.build): desktop-packaging · Desktop entry, schema, metainfo, and service packaging. · `data/meson.build`

## Connections

- Main → App: starts · Entry point initializes the application object.
- App → Window: presents · Application creates and shows the main window.
- Window → Home: contains · Main shell hosts the home page.
- Window → ROMs: contains · Main shell hosts the ROM browsing and transfer page.
- Window → Settings: contains · Main shell opens settings.
- ROMs → ROM Card: uses · ROM page renders individual ROM items.
- ROMs → USB Transfer: routes · Selects the USB transfer path when needed.
- ROMs → Net Transfer: routes · Selects the wireless transfer path when needed.
- ROMs → ROM Data: consumes · Page reads selected ROM metadata and state.
- ROMs → Finder: discovers · Search and file picking feed ROM selection.
- ROM Card → Progress: shows · Per-ROM UI displays transfer progress.
- Settings → Config: edits · Settings page reads and updates persistent configuration.
- Home → ROM Data: summarizes · Home page surfaces ROM-related state.
- USB Transfer → USB: starts · USB transfer UI initiates backend transfers.
- Net Transfer → Remote: starts · Wireless transfer UI initiates remote sessions.
- USB → Device Manager: uses · USB transport relies on device access abstraction.
- Device Manager → gudev: native · Native Linux discovery backend.
- Device Manager → Portal: sandboxed · Flatpak/portal access path.
- USB → Async Proto: speaks · Transfers use an async protocol layer.
- USB → Daemon: coordinates · Backend coordinates with the transfer daemon.
- Remote → Server: serves · Wireless backend exposes a session server.
- Remote → Reader: parses · Wireless backend reads incoming stream data.
- App → Resources: loads · Application loads bundled UI resources.
- App → Style: applies · Application applies global styling.
- App → Desktop Data: integrates · Packaging metadata supports desktop and service integration.
- ROMs → USB: reports · USB transfer progress and status flow back to the UI.
- ROMs → Remote: reports · Wireless transfer progress and status flow back to the UI.
- Utils → Finder: supports · Shared helpers assist discovery and selection.
- Utils → USB: supports · Shared helpers are reused by transfer code.
- Utils → Remote: supports · Shared helpers are reused by wireless code.
- Config → Device Manager: influences · Settings affect transport access mode and behavior.
