How monero-project/monero-gui works
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: libwalletqt Wallet bridge · pages Wallet pages · LeftPanel.qml Panels · main.qml Main QML
Components 22
Presentation
QML screens, reusable controls, and navigation shell.
- Main QML · Root UI shell that hosts the wallet navigation and content areas.
main.qml - Panels · Primary wallet navigation and content split across the left and middle panels.
LeftPanel.qml - Wallet pages · Main wallet feature screens such as account, receive, transfer, history, keys, mining, and settings.
pages - Onboarding wizard · Wallet creation, restore, open, and daemon/node setup flow.
wizard - UI components · 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 · 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 · Starts the GUI, initializes services, and launches QML.
src/main/main.cpp - MainApp · Wires startup concerns like logging, clipboard, cursor, and QML engine setup.
src/main/MainApp.cpp - Wallet bridge · Qt-facing wrapper around wallet objects, transactions, addresses, and sync events.
src/libwalletqt - Wallet manager · Creates, opens, and manages wallet instances.
src/libwalletqt/WalletManager.cpp - Wallet core · Core wallet state and operations exposed to the GUI layer.
src/libwalletqt/Wallet.cpp - Transactions · Transaction history, pending, unsigned, and info objects used by transfer flows.
src/libwalletqt/TransactionHistory.cpp - Address data · Address book, subaddress accounts, and subaddress handling.
src/libwalletqt/AddressBook.cpp - Daemon manager · Controls local daemon lifecycle and remote node connection behavior.
src/daemon/DaemonManager.cpp - Network tools · Networking, downloader, updater, IPC, and utility helpers used by the GUI.
src/qt - Platform helpers · OS-specific glue such as macOS helpers, Tails behavior, and network access blocking.
src/qt/macoshelper.mm - QR scanner · Native QR decoding and scan-thread pipeline for payment and wallet codes.
src/QR-Code-scanner - QR image · Provides QR images and UI-facing QR rendering support.
src/libwalletqt/QRCodeImageProvider.cpp - P2Pool · P2Pool-related GUI support and status integration.
src/p2pool/P2PoolManager.cpp
Assets & i18n
Packaged resources, translations, and UI assets.
- Translations · Qt translation catalogs and runtime translation loading.
translations - Assets · Icons, fonts, themes, and packaged QML resources.
qml.qrc
Build & packaging
Build system, installers, and delivery artifacts.
- Build & packaging · CMake build, Docker images, installers, Flatpak, and CI workflows.
CMakeLists.txt
Connections 22
- 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.