From 096f8ee90e1cd6a581f9f4c64243bf070c7f159e Mon Sep 17 00:00:00 2001 From: DanS Date: Sat, 4 Apr 2026 11:14:31 -0500 Subject: [PATCH] docs: add copilot-instructions.md and file-level comments - Create .github/copilot-instructions.md with project coding standards, architecture overview, threading model, and key rules for AI sessions - Add module description comments to app.cpp, rpc_client.cpp, rpc_worker.cpp, embedded_daemon.cpp, xmrig_manager.cpp, console_tab.cpp, settings.cpp - Add ASCII connection state diagram to app_network.cpp - Remove /.github/ from .gitignore so instructions file is tracked --- .github/copilot-instructions.md | 175 ++++++++++++++++++++++++++++++++ .gitignore | 1 - src/app.cpp | 3 + src/app_network.cpp | 26 ++++- src/config/settings.cpp | 3 + src/daemon/embedded_daemon.cpp | 3 + src/daemon/xmrig_manager.cpp | 3 + src/rpc/rpc_client.cpp | 3 + src/rpc/rpc_worker.cpp | 3 + src/ui/windows/console_tab.cpp | 3 + 10 files changed, 221 insertions(+), 2 deletions(-) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..f2e0e82 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,175 @@ +# ObsidianDragon — Coding Standards & Architecture + +## Project Identity + +ObsidianDragon is a native C++17 desktop wallet for the DragonX (DRGX) cryptocurrency. +It uses ImGui (immediate-mode GUI) with SDL3, ships an embedded full-node daemon (`dragonxd`), +and includes an integrated CPU miner (`xmrig-hac`). Licensed GPLv3. + +Platforms: Linux (x86_64), Windows (x86_64, cross-compiled via MinGW), macOS (universal arm64+x86_64). + +## Code Style + +### Naming +- **Classes/structs/enums:** `CamelCase` — `RPCClient`, `WalletState`, `NavPage` +- **Member variables:** `snake_case_` with trailing underscore — `rpc_`, `connection_status_`, `fast_worker_` +- **Functions/methods:** `camelCase` — `tryConnect()`, `isConnected()`, `drainResults()` +- **Constants:** `UPPER_SNAKE` for macros, `camelCase` for const vars — `REFRESH_INTERVAL`, `DEFAULT_FEE` +- **Enum values:** `CamelCase` — `NavPage::Overview`, `State::Running` +- **Type aliases:** `using MainCb = std::function;` + +### Formatting +- 4-space indentation, no tabs +- Opening brace on same line: `void foo() {` +- `#pragma once` (not include guards) +- Include order: self header, standard library, third-party, project headers + +### Memory & Ownership +- `std::unique_ptr` for ownership — never raw `new`/`delete` +- Raw pointers for non-owning references (e.g., function parameters) +- RAII for all resource management (threads, handles, mutexes) + +### Documentation +- `///` Doxygen comments on public APIs in headers +- Implementation files: explain *why*, not *what* +- Use `DEBUG_LOGF()` for debug logging, not `printf`/`std::cout` + +## Threading Model + +**Main thread** — ImGui render loop (`App::update()`), all UI code, `drainResults()` callbacks. +Never block this thread with network I/O or disk I/O. + +**`worker_`** (RPCWorker) — General-purpose background thread for batched RPC polling. +Executes the `refreshData()` cycle every 5 seconds. + +**`fast_worker_`** (RPCWorker) — Fast-lane background thread for latency-sensitive operations: +console commands, mining hashrate polls. Avoids head-of-line blocking behind main refresh batch. + +**Monitor threads** — `EmbeddedDaemon` and `XmrigManager` each spawn a monitor thread +to read stdout/stderr pipes from their child processes. + +### Work Submission Pattern +```cpp +// Post work to background thread; return a callback for the main thread +worker_->post([this]() -> rpc::RPCWorker::MainCb { + json result = rpc_->call("getinfo"); // Runs on worker thread (blocking OK) + return [this, result]() { + state_.connected = true; // Runs on main thread via drainResults() + }; +}); +``` +`drainResults()` is called each frame in `App::update()` to execute completed callbacks. + +## RPC Architecture + +**Dual-client design:** +- `rpc_` + `worker_` — main polling (balance, transactions, sync status) +- `fast_rpc_` + `fast_worker_` — console commands, mining stats + +Both are `RPCClient` instances wrapping libcurl for JSON-RPC over HTTPS. + +**Callback types:** +```cpp +using Callback = std::function; +using ErrorCallback = std::function; +``` + +**Error flow:** RPC errors throw `std::runtime_error` → caught in `doRPC()` → invokes +`ErrorCallback` → surfaces via `Notifications::instance().error(msg)`. + +**Connection state:** `state_.connected` (app-level, set in `onConnected()`) vs +`rpc_->isConnected()` (per-client, set after successful `getinfo()`). These can differ — +always check the right one for the context. + +## Connection Lifecycle + +``` +[Disconnected] → tryConnect() every 5s + → auto-detect DRAGONX.conf (host, port, rpcuser, rpcpassword) + → if no config: start embedded daemon → retry + → post async rpc_->connect() to worker_ + → success: onConnected() → state_.connected = true + → auth 401: try .cookie auth → retry + → failure: onDisconnected(reason) → may restart daemon +``` + +## UI Patterns + +### Page Routing +`NavPage` enum in `src/ui/sidebar.h` defines all pages. `App::update()` dispatches +via switch on `current_page_` to render functions like `RenderBalanceTab(this)` or +`console_tab_.render(...)`. + +### Dialogs +Modal dialogs use `show_*` boolean flags (e.g., `show_import_key_`, `show_backup_`). +Set the flag to `true` to open; the dialog renders in `App::update()` and clears +the flag when dismissed. + +### Notifications +```cpp +Notifications::instance().success("Transaction sent"); +Notifications::instance().error("Insufficient funds"); +``` +Toast-style popups in the bottom-right corner. + +### Lock Screen & Loading Overlay +- Lock screen gates all interaction when `state_.isLocked()` +- Loading overlay shown while daemon isn't ready, gates all tabs except Peers, Console, Settings + +## Platform Abstractions + +Detection: `#ifdef _WIN32` / `#elif __APPLE__` / `#elif __linux__` + +Platform-specific files live in `src/platform/` (Windows only: DX11 context, backdrop effects). +Shared platform utilities in `src/util/platform.h` — `openUrl()`, `getHomeDir()`, `getDragonXDataDir()`. + +Rendering backends: +- Windows: DirectX 11 (`imgui_impl_dx11`) +- macOS/Linux: OpenGL 3 (`imgui_impl_opengl3`) + GLAD loader + +## Build System + +CMake 3.20+, C++17. Single `CMakeLists.txt` at root. + +**FetchContent dependencies:** SDL3, nlohmann/json v3.11.3, toml++ v3.4.0, libcurl (Windows only) +**Bundled libraries:** ImGui, GLAD, miniz, libsodium (pre-built per platform), qrcode + +**macOS:** Universal binary (arm64+x86_64), deployment target 11.0 (Big Sur+). +Set `CMAKE_OSX_DEPLOYMENT_TARGET` and `CMAKE_OSX_ARCHITECTURES` before `project()`. + +**Build commands:** +```bash +./build.sh # Dev build +./build.sh --mac-release # macOS universal .app + DMG +./build.sh --linux-release # Linux AppImage + zip +./build.sh --win-release # Windows cross-compile +``` + +## Theme System + +UI layout values are defined in `res/themes/ui.toml` and accessed via `schema::UI()` — +**never hardcode pixel sizes in C++ code**. + +Skins are self-contained TOML files in `res/themes/` defining color palettes. +`scripts/expand_themes.py` merges layout sections from `ui.toml` into each skin at build time. + +Colors support CSS-style variables: `--primary`, `--surface`, `--on-surface-medium`, resolved +by `ColorVarResolver` at runtime. + +## Internationalization + +All user-visible strings use `TR("key")` macro → `dragonx::util::tr()` → lookup in +`I18n` singleton. Never hardcode English strings in UI code. + +Language files: `res/lang/{locale}.json` (runtime) with embedded fallback compiled into binary. +Supported: en, es, zh, ru, de, fr, pt, ja, ko. + +## Key Rules + +1. **Never block the main thread** — all network/disk I/O goes through `worker_->post()` +2. **Never hardcode pixel sizes** — use `ui.toml` schema values via `schema::UI()` +3. **Always use `TR()` for strings** — no hardcoded English in UI rendering code +4. **Use `ICON_MD_*` for icons** — Material Design icon font, never raw Unicode +5. **Use `std::unique_ptr`** — no raw `new`/`delete` in application code +6. **Check the right connection state** — `state_.connected` for app-level, `rpc_->isConnected()` for per-client +7. **Test all three platforms** — build must pass Linux; cross-compile test if touching platform code diff --git a/.gitignore b/.gitignore index c83c350..5216bfd 100644 --- a/.gitignore +++ b/.gitignore @@ -36,7 +36,6 @@ asmap.dat /external/xmrig-hac /memory /todo.md -/.github/ # macOS .DS_Store \ No newline at end of file diff --git a/src/app.cpp b/src/app.cpp index 5f4b27c..e2c785a 100644 --- a/src/app.cpp +++ b/src/app.cpp @@ -1,6 +1,9 @@ // DragonX Wallet - ImGui Edition // Copyright 2024-2026 The Hush Developers // Released under the GPLv3 +// +// app.cpp — Main application: init, shutdown, ImGui render loop, NavPage +// dispatch, dialog rendering, and frame-level state management. #include "app.h" #include "config/version.h" diff --git a/src/app_network.cpp b/src/app_network.cpp index 425a725..6dddf64 100644 --- a/src/app_network.cpp +++ b/src/app_network.cpp @@ -2,8 +2,32 @@ // Copyright 2024-2026 The Hush Developers // Released under the GPLv3 // -// app_network.cpp — RPC connection, data refresh, and network operations +// app_network.cpp — RPC connection, data refresh, and network operations. // Split from app.cpp for maintainability. +// +// Connection state machine: +// +// [Disconnected] +// │ +// ▼ tryConnect() every 5s +// Auto-detect DRAGONX.conf (host, port, rpcuser, rpcpassword) +// │ +// ├─ no config found ──► start embedded daemon ──► retry +// │ +// ▼ post async rpc_->connect() to worker_ +// [Connecting] +// │ +// ├─ success ──► onConnected() ──► [Connected] +// │ │ +// │ ▼ refreshData() every 5s +// │ [Running] +// │ │ +// │ ├─ RPC error ──► onDisconnected() +// │ │ │ +// ├─ auth 401 ──► .cookie auth ──► retry│ ▼ +// │ │ [Disconnected] +// └─ failure ──► onDisconnected(reason) ┘ +// may restart daemon #include "app.h" #include "rpc/rpc_client.h" diff --git a/src/config/settings.cpp b/src/config/settings.cpp index 2db3397..1ec9a73 100644 --- a/src/config/settings.cpp +++ b/src/config/settings.cpp @@ -1,6 +1,9 @@ // DragonX Wallet - ImGui Edition // Copyright 2024-2026 The Hush Developers // Released under the GPLv3 +// +// settings.cpp — JSON settings persistence. Loads/saves user preferences +// to ~/.config/ObsidianDragon/settings.json (Linux/macOS) or %APPDATA% (Windows). #include "settings.h" #include "version.h" diff --git a/src/daemon/embedded_daemon.cpp b/src/daemon/embedded_daemon.cpp index 3f2642a..db3831a 100644 --- a/src/daemon/embedded_daemon.cpp +++ b/src/daemon/embedded_daemon.cpp @@ -1,6 +1,9 @@ // DragonX Wallet - ImGui Edition // Copyright 2024-2026 The Hush Developers // Released under the GPLv3 +// +// embedded_daemon.cpp — Manages the dragonxd child process lifecycle: +// binary discovery, process spawn, stdout/stderr monitoring, crash recovery. #include "embedded_daemon.h" #include "../config/version.h" diff --git a/src/daemon/xmrig_manager.cpp b/src/daemon/xmrig_manager.cpp index fb6ac79..9daa411 100644 --- a/src/daemon/xmrig_manager.cpp +++ b/src/daemon/xmrig_manager.cpp @@ -1,6 +1,9 @@ // DragonX Wallet - ImGui Edition // Copyright 2024-2026 The Hush Developers // Released under the GPLv3 +// +// xmrig_manager.cpp — Pool mining process management via xmrig-hac. +// Spawns xmrig, monitors via HTTP API, tracks hashrate and shares. #include "xmrig_manager.h" #include "../resources/embedded_resources.h" diff --git a/src/rpc/rpc_client.cpp b/src/rpc/rpc_client.cpp index bf936ce..e2e0020 100644 --- a/src/rpc/rpc_client.cpp +++ b/src/rpc/rpc_client.cpp @@ -1,6 +1,9 @@ // DragonX Wallet - ImGui Edition // Copyright 2024-2026 The Hush Developers // Released under the GPLv3 +// +// rpc_client.cpp — JSON-RPC client over HTTPS using libcurl. +// All calls are blocking; run on RPCWorker threads, never on main thread. #include "rpc_client.h" #include "../config/version.h" diff --git a/src/rpc/rpc_worker.cpp b/src/rpc/rpc_worker.cpp index 33455ec..5276d9e 100644 --- a/src/rpc/rpc_worker.cpp +++ b/src/rpc/rpc_worker.cpp @@ -1,6 +1,9 @@ // DragonX Wallet - ImGui Edition // Copyright 2024-2026 The Hush Developers // Released under the GPLv3 +// +// rpc_worker.cpp — Background work queue. Executes WorkFn on its own thread, +// returns MainCb callbacks drained each frame on the main thread. #include "rpc_worker.h" #include diff --git a/src/ui/windows/console_tab.cpp b/src/ui/windows/console_tab.cpp index 8b966c9..f279684 100644 --- a/src/ui/windows/console_tab.cpp +++ b/src/ui/windows/console_tab.cpp @@ -1,6 +1,9 @@ // DragonX Wallet - ImGui Edition // Copyright 2024-2026 The Hush Developers // Released under the GPLv3 +// +// console_tab.cpp — Interactive RPC console with command history, +// tab completion, daemon log display, and color-coded output. #include "console_tab.h" #include "../material/colors.h"