# monero-project/monero-gui architecture

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

- Interactive diagram: https://gitdiagram.com/monero-project/monero-gui
- Repository: https://github.com/monero-project/monero-gui

## Overview

1. **Overall shape**
   - This is a **Qt/QML desktop wallet GUI** for Monero, with optional Android packaging.
   - The architecture is a classic split between a **QML presentation layer** and a **C++ backend/service layer** that wraps Monero wallet and daemon functionality.

2. **Application entry and shell**
   - The runtime starts in `src/main/main.cpp`, then `MainApp` and related startup code wire together translation loading, platform helpers, clipboard, cursor, logging, and the QML engine.
   - `main.qml` is the root UI shell, with `LeftPanel.qml`, `MiddlePanel.qml`, and the various `pages/*` files composing the main navigation and content area.

3. **Primary UI modules**
   - `pages/` contains the main wallet features: account, receive, transfer, history, address book, keys, mining, sign/tx key, advanced settings, and merchant views.
   - `wizard/` is a separate onboarding flow for creating, restoring, opening, or configuring wallets and daemon/node settings.
   - `components/` is a reusable UI library of controls, dialogs, styles, and effects used across both the wizard and the main wallet screens.

4. **UI state and model layer**
   - `src/model/` provides Qt models that back list/table views in QML, especially address book, subaddress accounts, subaddresses, and transaction history.
   - The models act as the bridge between the UI and the wallet backend, converting wallet state into QML-friendly structures and sort/filter behavior.

5. **Wallet backend boundary**
   - `src/libwalletqt/` is the core bridge to Monero wallet functionality.
   - It wraps wallet concepts such as `Wallet`, `WalletManager`, `TransactionHistory`, `TransactionInfo`, `PendingTransaction`, `UnsignedTransaction`, `AddressBook`, `Subaddress`, and `SubaddressAccount`.
   - This is the main boundary where QML-visible actions become wallet operations such as opening a wallet, creating transactions, managing addresses, and observing sync/activity updates.

6. **Daemon and node management**
   - `src/daemon/DaemonManager.*` manages the daemon side of the application, which can mean local daemon lifecycle control or connection handling to a remote node.
   - The wizard and settings pages expose node selection and daemon configuration, so node/daemon state is a first-class part of the app rather than a hidden dependency.

7. **Network, update, and OS integration**
   - `src/qt/` contains cross-cutting application services: networking, updater/downloader, utility helpers, Tails-specific behavior, settings, IPC, and OS-specific integrations.
   - This layer also includes platform code such as macOS helpers and network access blocking, which are used to adapt the GUI to the host environment and to control external connectivity behavior.

8. **QR scanning and image generation**
   - `src/QR-Code-scanner/` provides a native QR decoding pipeline for scanning payment data or wallet-related codes.
   - `src/libwalletqt/QRCodeImageProvider.*` and `components/QRCodeScanner.qml` connect that native functionality to the UI for rendering or capturing QR data.

9. **Mining and pool-related features**
   - `src/p2pool/P2PoolManager.*` indicates built-in support for P2Pool-related workflows from the GUI.
   - The `pages/Mining.qml` screen is the user-facing entry point for mining/pool configuration and status.

10. **Security and key handling helpers**
   - `src/libwalletqt/PassphraseHelper.*`, `src/qt/KeysFiles.*`, and the password/device dialogs in `components/` support encrypted wallet access and key-file handling.
   - `src/openpgp/` and `src/zxcvbn-c/` are bundled native helpers for crypto-related serialization/handling and password strength estimation.

11. **Localization and assets**
   - `translations/` contains the Qt translation catalogs, loaded at runtime through `src/TranslationManager.*`.
   - Static assets live in `images/`, `fonts/`, `lang/`, and `qml.qrc`, which package the UI theme, icons, language metadata, and resource files into the executable.

12. **External dependency boundary**
   - The GUI depends on the **Monero core project** as a submodule/binary dependency boundary rather than reimplementing the protocol itself.
   - It is built on **Qt Quick/QML** with a CMake-based native layer, and uses bundled third-party code such as `quirc` for QR decoding.

13. **Build and packaging pipeline**
   - The repository supports local builds, reproducible Docker builds, Windows installers, Android APKs, Flatpak packaging, and CI via GitHub Actions.
   - Packaging assets live under `installers/`, `share/`, and the platform-specific Dockerfiles, which means the repo is structured to produce distributable desktop/mobile artifacts from the same codebase.

14. **How data flows through the app**
   - User actions begin in QML pages/components, move through models and controllers, then into the C++ backend services.
   - Backend services talk to wallet/daemon/network subsystems, and results flow back as Qt signals/models that update the UI, sync state, balances, history, and transaction status.

15. **Useful diagram boundaries**
   - The cleanest architecture diagram would separate:
     - **Presentation**: QML pages, wizard, components
     - **State/models**: Qt models for wallet data
     - **Native services**: wallet, daemon, p2pool, updater, QR, OS integration
     - **External runtime**: Monero daemon/network and platform packaging/binaries

Main entry points: [`src/libwalletqt`](https://github.com/monero-project/monero-gui/tree/master/src/libwalletqt) (Wallet bridge), [`pages`](https://github.com/monero-project/monero-gui/tree/master/pages) (Wallet pages), [`LeftPanel.qml`](https://github.com/monero-project/monero-gui/blob/master/LeftPanel.qml) (Panels), [`main.qml`](https://github.com/monero-project/monero-gui/blob/master/main.qml) (Main QML)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_main_qml["Main QML<br/>qml shell<br/>[main.qml]"]
  node_nav_panels["Panels<br/>qml layout<br/>[LeftPanel.qml]"]
  node_pages["Wallet pages<br/>qml screens"]
  node_wizard["Onboarding wizard<br/>qml flow"]
  node_components["UI components<br/>qml library"]
end

subgraph group_state["State & models"]
  node_models["Qt models<br/>model layer"]
end

subgraph group_services["Native services"]
  node_main_cpp["App entry<br/>entrypoint<br/>[main.cpp]"]
  node_mainapp["MainApp<br/>app shell<br/>[MainApp.cpp]"]
  node_walletqt["Wallet bridge<br/>backend bridge"]
  node_wallet_mgr["Wallet manager<br/>wallet lifecycle<br/>[WalletManager.cpp]"]
  node_wallet_core["Wallet core<br/>wallet object<br/>[Wallet.cpp]"]
  node_tx_domain["Transactions<br/>tx domain"]
  node_addr_domain["Address data<br/>address domain<br/>[AddressBook.cpp]"]
  node_daemon["Daemon manager<br/>node control<br/>[DaemonManager.cpp]"]
  node_net_services["Network tools<br/>service set"]
  node_platform_helpers["Platform helpers<br/>os integration<br/>[macoshelper.mm]"]
  node_qr_scan["QR scanner<br/>qr pipeline"]
  node_qr_image["QR image<br/>image provider"]
  node_p2pool["P2Pool<br/>mining service<br/>[P2PoolManager.cpp]"]
end

subgraph group_assets["Assets & i18n"]
  node_localization["Translations<br/>i18n"]
  node_resources["Assets<br/>resource pack<br/>[qml.qrc]"]
end

subgraph group_build["Build & packaging"]
  node_build_packaging["Build & packaging<br/>build system<br/>[CMakeLists.txt]"]
end

node_main_cpp -->|"starts"| node_mainapp
node_mainapp -->|"loads"| node_main_qml
node_main_qml -->|"hosts"| node_nav_panels
node_nav_panels -->|"routes to"| node_pages
node_nav_panels -->|"launches"| node_wizard
node_pages -->|"uses"| node_components
node_wizard -->|"uses"| node_components
node_pages -->|"binds to"| node_models
node_models -->|"adapts"| node_walletqt
node_walletqt -->|"wraps"| node_wallet_mgr
node_walletqt -->|"exposes"| node_wallet_core
node_walletqt -->|"tracks"| node_tx_domain
node_walletqt -->|"manages"| node_addr_domain
node_walletqt -->|"coordinates"| node_daemon
node_walletqt -->|"renders"| node_qr_image
node_qr_scan -->|"integrates with"| node_components
node_net_services -->|"adapts"| node_platform_helpers
node_p2pool -->|"shown in"| node_pages
node_localization -->|"loaded by"| node_mainapp
node_resources -->|"packages"| node_main_qml
node_build_packaging -->|"includes"| node_resources
node_build_packaging -->|"compiles"| node_main_cpp

click node_main_cpp "https://github.com/monero-project/monero-gui/blob/master/src/main/main.cpp"
click node_mainapp "https://github.com/monero-project/monero-gui/blob/master/src/main/MainApp.cpp"
click node_main_qml "https://github.com/monero-project/monero-gui/blob/master/main.qml"
click node_nav_panels "https://github.com/monero-project/monero-gui/blob/master/LeftPanel.qml"
click node_pages "https://github.com/monero-project/monero-gui/tree/master/pages"
click node_wizard "https://github.com/monero-project/monero-gui/tree/master/wizard"
click node_components "https://github.com/monero-project/monero-gui/tree/master/components"
click node_models "https://github.com/monero-project/monero-gui/tree/master/src/model"
click node_walletqt "https://github.com/monero-project/monero-gui/tree/master/src/libwalletqt"
click node_wallet_mgr "https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/WalletManager.cpp"
click node_wallet_core "https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/Wallet.cpp"
click node_tx_domain "https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/TransactionHistory.cpp"
click node_addr_domain "https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/AddressBook.cpp"
click node_daemon "https://github.com/monero-project/monero-gui/blob/master/src/daemon/DaemonManager.cpp"
click node_net_services "https://github.com/monero-project/monero-gui/tree/master/src/qt"
click node_platform_helpers "https://github.com/monero-project/monero-gui/blob/master/src/qt/macoshelper.mm"
click node_qr_scan "https://github.com/monero-project/monero-gui/tree/master/src/QR-Code-scanner"
click node_qr_image "https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/QRCodeImageProvider.cpp"
click node_p2pool "https://github.com/monero-project/monero-gui/blob/master/src/p2pool/P2PoolManager.cpp"
click node_localization "https://github.com/monero-project/monero-gui/tree/master/translations"
click node_resources "https://github.com/monero-project/monero-gui/blob/master/qml.qrc"
click node_build_packaging "https://github.com/monero-project/monero-gui/blob/master/CMakeLists.txt"

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_qml,node_nav_panels,node_pages,node_wizard,node_components toneBlue
class node_models toneAmber
class node_main_cpp,node_mainapp,node_walletqt,node_wallet_mgr,node_wallet_core,node_tx_domain,node_addr_domain,node_daemon,node_net_services,node_platform_helpers,node_qr_scan,node_qr_image,node_p2pool toneMint
class node_localization,node_resources toneRose
class node_build_packaging toneIndigo
```

## Components

### Presentation

QML screens, reusable controls, and navigation shell.

- [Main QML](https://github.com/monero-project/monero-gui/blob/master/main.qml): qml shell · Root UI shell that hosts the wallet navigation and content areas. · `main.qml`
- [Panels](https://github.com/monero-project/monero-gui/blob/master/LeftPanel.qml): qml layout · Primary wallet navigation and content split across the left and middle panels. · `LeftPanel.qml`
- [Wallet pages](https://github.com/monero-project/monero-gui/tree/master/pages): qml screens · Main wallet feature screens such as account, receive, transfer, history, keys, mining, and settings. · `pages`
- [Onboarding wizard](https://github.com/monero-project/monero-gui/tree/master/wizard): qml flow · Wallet creation, restore, open, and daemon/node setup flow. · `wizard`
- [UI components](https://github.com/monero-project/monero-gui/tree/master/components): qml library · Reusable controls, dialogs, styles, and effects shared by the app and wizard. · `components`

### State & models

Qt models that adapt wallet data for the UI.

- [Qt models](https://github.com/monero-project/monero-gui/tree/master/src/model): model layer · List and table models that expose wallet state to QML views. · `src/model`

### Native services

C++ backend services for wallet, daemon, network, and platform integration.

- [App entry](https://github.com/monero-project/monero-gui/blob/master/src/main/main.cpp): entrypoint · Starts the GUI, initializes services, and launches QML. · `src/main/main.cpp`
- [MainApp](https://github.com/monero-project/monero-gui/blob/master/src/main/MainApp.cpp): app shell · Wires startup concerns like logging, clipboard, cursor, and QML engine setup. · `src/main/MainApp.cpp`
- [Wallet bridge](https://github.com/monero-project/monero-gui/tree/master/src/libwalletqt): backend bridge · Qt-facing wrapper around wallet objects, transactions, addresses, and sync events. · `src/libwalletqt`
- [Wallet manager](https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/WalletManager.cpp): wallet lifecycle · Creates, opens, and manages wallet instances. · `src/libwalletqt/WalletManager.cpp`
- [Wallet core](https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/Wallet.cpp): wallet object · Core wallet state and operations exposed to the GUI layer. · `src/libwalletqt/Wallet.cpp`
- [Transactions](https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/TransactionHistory.cpp): tx domain · Transaction history, pending, unsigned, and info objects used by transfer flows. · `src/libwalletqt/TransactionHistory.cpp`
- [Address data](https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/AddressBook.cpp): address domain · Address book, subaddress accounts, and subaddress handling. · `src/libwalletqt/AddressBook.cpp`
- [Daemon manager](https://github.com/monero-project/monero-gui/blob/master/src/daemon/DaemonManager.cpp): node control · Controls local daemon lifecycle and remote node connection behavior. · `src/daemon/DaemonManager.cpp`
- [Network tools](https://github.com/monero-project/monero-gui/tree/master/src/qt): service set · Networking, downloader, updater, IPC, and utility helpers used by the GUI. · `src/qt`
- [Platform helpers](https://github.com/monero-project/monero-gui/blob/master/src/qt/macoshelper.mm): os integration · OS-specific glue such as macOS helpers, Tails behavior, and network access blocking. · `src/qt/macoshelper.mm`
- [QR scanner](https://github.com/monero-project/monero-gui/tree/master/src/QR-Code-scanner): qr pipeline · Native QR decoding and scan-thread pipeline for payment and wallet codes. · `src/QR-Code-scanner`
- [QR image](https://github.com/monero-project/monero-gui/blob/master/src/libwalletqt/QRCodeImageProvider.cpp): image provider · Provides QR images and UI-facing QR rendering support. · `src/libwalletqt/QRCodeImageProvider.cpp`
- [P2Pool](https://github.com/monero-project/monero-gui/blob/master/src/p2pool/P2PoolManager.cpp): mining service · P2Pool-related GUI support and status integration. · `src/p2pool/P2PoolManager.cpp`

### Assets & i18n

Packaged resources, translations, and UI assets.

- [Translations](https://github.com/monero-project/monero-gui/tree/master/translations): i18n · Qt translation catalogs and runtime translation loading. · `translations`
- [Assets](https://github.com/monero-project/monero-gui/blob/master/qml.qrc): resource pack · Icons, fonts, themes, and packaged QML resources. · `qml.qrc`

### Build & packaging

Build system, installers, and delivery artifacts.

- [Build & packaging](https://github.com/monero-project/monero-gui/blob/master/CMakeLists.txt): build system · CMake build, Docker images, installers, Flatpak, and CI workflows. · `CMakeLists.txt`

## Connections

- App entry → MainApp: starts · Program entry initializes the application shell.
- MainApp → Main QML: loads · App shell creates and configures the root QML engine.
- Main QML → Panels: hosts · Root shell arranges the main navigation panels.
- Panels → Wallet pages: routes to · Main navigation opens wallet feature pages.
- Panels → Onboarding wizard: launches · Onboarding flow is a separate UI path.
- Wallet pages → UI components: uses · Wallet screens are built from shared controls and dialogs.
- Onboarding wizard → UI components: uses · Wizard screens reuse the shared QML component library.
- Wallet pages → Qt models: binds to · Feature screens read and sort wallet data through Qt models.
- Qt models → Wallet bridge: adapts · Models transform backend wallet state into QML-friendly data.
- Wallet bridge → Wallet manager: wraps · Bridge layer manages wallet lifecycle and access.
- Wallet bridge → Wallet core: exposes · Bridge layer surfaces wallet operations and state.
- Wallet bridge → Transactions: tracks · Transaction-related classes power send/history flows.
- Wallet bridge → Address data: manages · Address and subaddress data flow through the bridge.
- Wallet bridge → Daemon manager: coordinates · Wallet actions depend on daemon and node connectivity.
- Wallet bridge → QR image: renders · QR generation is exposed for the UI.
- QR scanner → UI components: integrates with · Scanner UI connects native decoding with QML controls.
- Network tools → Platform helpers: adapts · Cross-cutting network and OS utilities integrate with host environment.
- P2Pool → Wallet pages: shown in · Mining page exposes P2Pool workflows and status.
- Translations → MainApp: loaded by · Runtime translation loading is part of startup.
- Assets → Main QML: packages · UI resources and assets are embedded into the application.
- Build & packaging → Assets: includes · Build pipeline bundles static assets and translations.
- Build & packaging → App entry: compiles · Native build produces the application executable and support libraries.