# Codebase Overview

Current as of 2026-04-27 for ObsidianDragon `1.2.0-rc1`.

## Purpose

ObsidianDragon is a Dear ImGui full-node wallet for DragonX (DRGX). It manages an embedded or external `dragonxd`, renders a schema-driven desktop UI, and provides shielded transactions, mining, market data, address management, explorer tools, and bootstrap download support.

## Runtime Architecture

- `src/main.cpp` initializes SDL3, graphics backends, ImGui, and the main loop.
- `src/app.cpp` owns application lifecycle, navigation, rendering, dialogs, and daemon/RPC startup.
- `src/app_network.cpp` contains refresh and transaction flows, including balance, address, transaction, mining, market, peer, and address metadata updates.
- `src/app_security.cpp` covers wallet encryption, PIN unlock, auto-lock, and secure vault integration.
- `src/app_wizard.cpp` handles first-run setup and bootstrap/encryption flow.

The UI thread renders ImGui and drains callback queues. RPC work runs through `RPCWorker`, which posts worker-thread RPC calls and returns UI-thread callbacks. Console commands can use a separate fast-lane RPC client/worker so they do not queue behind regular refresh batches.

`NetworkRefreshService` owns refresh timing, named job enqueue/callback guards, typed refresh result models, and service-owned result applicators for connection, core balance/sync, encryption, mining, peers, price, address snapshots, and transaction cache updates. Warmup polling, connection-init, core, mining, peer, address, and transaction refresh collection now run through a testable `RefreshRpcGateway`, and price HTTP response evaluation has a service-owned status/error/result model. `App` keeps enqueueing, UI timing decisions, cadence decisions, libcurl execution, and application handoff code for those paths.

## Source Map

| Path | Role |
|------|------|
| `src/config/` | Settings JSON persistence and generated `version.h` |
| `src/data/` | Wallet state, address book, exchange info |
| `src/rpc/` | libcurl JSON-RPC client, connection config, worker queue |
| `src/daemon/` | Embedded `dragonxd` manager and xmrig pool miner manager |
| `src/ui/windows/` | Main tabs and modal dialogs |
| `src/ui/pages/` | Page-style screens such as Settings |
| `src/ui/schema/` | TOML schema loader, skin manager, color resolver |
| `src/ui/material/` | Material-style typography, layout, drawing, components |
| `src/ui/effects/` | Acrylic, blur, noise, theme effects, low-spec fallback |
| `src/resources/` | Embedded resource extraction for params, daemon assets, themes, images |
| `src/platform/` | Windows DX11 and backdrop helpers |
| `src/util/` | i18n, logging, platform paths, bootstrap, vault, URI/base64/texture utilities |

## Build And Resources

- CMake uses C++17 and outputs `build/bin/ObsidianDragon`.
- Version comes from `project(... VERSION 1.2.0)` plus `DRAGONX_VERSION_SUFFIX=-rc1`.
- `src/config/version.h` is intentionally committed source for editor/release tooling compatibility, but CMake regenerates it from `src/config/version.h.in` during configure. Version bumps should update the CMake version/suffix and commit the regenerated header with the template if it changes.
- SDL3 is found from the system first, then fetched by CMake if unavailable.
- nlohmann/json and toml++ are fetched with CMake FetchContent.
- libcurl is system-provided on Linux/macOS and fetched statically for Windows.
- libsodium is system-provided on Linux or local under `libs/libsodium/`, `libs/libsodium-win/`, or `libs/libsodium-mac/`.
- Fonts are embedded with INCBIN: Ubuntu, Material Icons, a one-glyph MDI pickaxe subset, and Noto CJK subset.
- `res/themes/ui.toml` is embedded as a fallback and expanded into build themes with `scripts/expand_themes.py`.
- `res/default_banlist.txt` is embedded into `build/generated/default_banlist_embedded.h`.

## RPC And Daemon Notes

- Default RPC port is `21769`.
- `RPCClient` uses local HTTP with Basic auth. TLS is not assumed for localhost daemon RPC.
- DragonX daemon config paths:
  - Linux: `~/.hush/DRAGONX/DRAGONX.conf`
  - Windows: `%APPDATA%/Hush/DRAGONX/DRAGONX.conf`
  - macOS: `~/Library/Application Support/Hush/DRAGONX/DRAGONX.conf`
- `Connection::autoDetectConfig()` creates missing config files, appends `exportdir`, `experimentalfeatures=1`, and `developerencryptwallet=1`, and falls back to `.cookie` auth if no `rpcpassword` is configured.
- The embedded daemon detects an external daemon on the RPC port and connects to it instead of taking ownership.
- Chain args include TLS-only mode, adaptive `-dbcache`, DragonX asset parameters, node seeds `node.dragonx.is` through `node4.dragonx.is`, and optional `-maxconnections=<n>` from Settings.

## UI And Data Notes

- Sidebar navigation is driven by `NavPage`: Overview, Send, Receive, History, Mining, Market, Console, Network, Explorer, Settings.
- Explorer lives in `src/ui/windows/explorer_tab.cpp`; Settings uses `src/ui/pages/settings_page.cpp`.
- Address labels, icons, favorites, hidden state, and manual ordering are persisted in Settings, especially `address_meta`.
- `AddressInfo::has_spending_key` tracks view-only shielded addresses; send flows filter or reject non-spendable z-addresses.
- The pickaxe icon is not a normal `ICON_MD_*` glyph. Use `AddressLabelDialog::drawIconByName()` or `Typography::pickaxeFontForSize()` for that special case.
- Remaining process-wide ImGui state and legacy compatibility wrappers are documented in `docs/ui-static-state.md`.
- Warmup, connection-init, core, mining, peer, address, and transaction refreshes use typed `NetworkRefreshService` result contracts plus gateway-backed collectors. Price refresh keeps libcurl setup/execution and callback ownership in App, while `NetworkRefreshService` owns JSON parsing plus HTTP status/error result evaluation. App still owns warmup status handoffs, mining fast/slow cadence, and command-style RPC actions. Transaction application updates `WalletState`, `viewtx_cache_`, `send_txids_`, the confirmed transaction cache, and block-height markers as one cache-update operation.

## Remaining Work

- Investigate `todo.md`: determine whether DragonX/Komodo wallet storage supports a safe compaction or consolidation workflow for wallets with too many addresses.
- Phase 23 should continue sustained maintenance mode: keep refresh and price boundaries stable, and revisit command/lifecycle/decrypt/UI-state seams only when concrete feature work creates a focused tested boundary.