# anushka2503769/wallet-ui architecture

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

- Interactive diagram: https://gitdiagram.com/anushka2503769/wallet-ui
- Repository: https://github.com/anushka2503769/wallet-ui

## Overview

1. **Overall shape**
   This repo is split into two major subsystems:
   - a **React/Vite frontend prototype** for the TradeFlow Wallet UI
   - a **Rust blockchain simulator/backend** under `rust-blockchain/`
   
   The frontend is currently the primary user-facing app; the Rust side appears to be a separate executable/service that will eventually back the UI.

2. **Frontend shell**
   The entry point is a single-page application built with **React + Vite** (`src/main.jsx`, `src/App.jsx`, `src/routes.jsx`).
   Routing is page-based, not server-rendered: the app navigates across dashboard, wallet, explorer, trading, staking, validators, and harness screens.

3. **Page-level domains**
   The `src/pages/` folder defines the product’s major functional areas:
   - **Dashboard / Portfolio / Transactions / SendReceive** for wallet operations
   - **Blockchain / Explorer / Validators / Staking** for chain visibility and participation
   - **Markets / FuturesTrading / OptionsTrading / PerpetualsTrading / OpenPositions / TradeHistory** for trading-oriented views
   - **Harness** for automated testing or simulation monitoring
   - **Settings** for user/app preferences
   
   These pages are mostly presentation and orchestration layers over shared components and service calls.

4. **Shared UI component system**
   Reusable UI lives in `src/components/` and is organized by domain:
   - `common/` for shell elements like header, sidebar, loading state, stat cards
   - `wallet/` for wallet cards and transaction form
   - `blockchain/` for block cards, block lists, network status
   - `tables/` and `charts/` for tabular and analytical views
   
   This indicates a design where pages assemble data-driven widgets rather than containing heavy logic themselves.

5. **State and cross-cutting concerns**
   App-wide state is managed with React context in `src/context/`:
   - `ThemeContext` handles dark/light mode
   - `WalletContext` manages wallet-related state across pages
   
   There is also a `useBlockchain` hook in `src/hooks/`, which centralizes blockchain-data access for components and pages that need chain state.

6. **Frontend data layer and abstraction boundary**
   The `src/services/` folder is the key boundary between UI and data sources:
   - `services/api/` contains HTTP client and wallet API wrappers
   - `services/blockchain/` contains a blockchain provider abstraction plus a mock provider
   - `services/harness/` contains simulation/test harness logic
   
   This structure suggests the UI is designed to swap between mocked local data and real backend integrations without changing page components.

7. **Mock-first development mode**
   The presence of `src/data/*.json` and `src/utils/mockDelay.js` shows the frontend currently runs heavily on **mock datasets** for:
   - blocks
   - transactions
   - portfolio
   - validators
   - harness logs
   
   This is an important architectural boundary: the UI can function independently of the Rust backend while still modeling the eventual real data flows.

8. **Rust blockchain subsystem**
   The `rust-blockchain/` directory is a separate Rust project (`Cargo.toml`, `src/main.rs`) with:
   - `cli.rs` for command-line interaction
   - `consensus.rs` for consensus logic
   - `ledger/` for persistent chain state
   - `blockchain_gui.py` as an auxiliary GUI/utility entry point
   
   The Rust project appears to implement blockchain behavior and persistence, not the React UI itself.

9. **Ledger and persistence model**
   The `ledger/` directory contains files like `CURRENT`, `IDENTITY`, `LOCK`, and `LOG`, which strongly suggests a **file-backed local ledger/store** rather than a remote database.
   
   That means chain state is likely persisted on disk inside the Rust subsystem, and the frontend would consume chain state through services or an API layer rather than directly.

10. **Likely end-to-end data flow**
   The intended flow is:
   - user interacts with a React page
   - page calls a shared service or hook
   - service reads mock JSON locally or calls an HTTP/API integration
   - blockchain-specific requests eventually map to the Rust backend or simulation layer
   
   For harness and validator views, data is probably sourced from simulation logs or mock streams rather than live chain polling today.

11. **Tooling and runtime boundaries**
   The frontend runs in a **Node/Vite browser runtime** and is styled through global/theme CSS files.
   The Rust subsystem runs as an independent **native binary**.
   This separation is useful for architecture diagrams: treat them as two deployable units with a loose integration boundary, not as one monolith.

12. **What to emphasize in an architecture diagram**
   The main boxes should be:
   - **React SPA shell**
   - **Route-based feature pages**
   - **Shared UI components**
   - **Contexts/hooks**
   - **Service layer with API + blockchain provider abstraction**
   - **Mock data / harness simulation sources**
   - **Rust blockchain engine with CLI, consensus, and file-backed ledger**
   
   The primary relationship is frontend orchestration over blockchain/testing data, with the Rust backend serving as the future authoritative chain engine.

Main entry points: [`src/routes.jsx`](https://github.com/anushka2503769/wallet-ui/blob/main/src/routes.jsx) (Routes), [`rust-blockchain/src/main.rs`](https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/src/main.rs) (Rust app), [`src/services/api/httpClient.js`](https://github.com/anushka2503769/wallet-ui/blob/main/src/services/api/httpClient.js) (Services), [`src/components/common/Header.jsx`](https://github.com/anushka2503769/wallet-ui/blob/main/src/components/common/Header.jsx) (Common UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_app_shell["App shell<br/>React/Vite SPA<br/>[main.jsx]"]
  node_app_routes["Routes<br/>navigation<br/>[routes.jsx]"]
  node_dashboard_page["Dashboard<br/>wallet page<br/>[Dashboard.jsx]"]
  node_wallet_pages["Wallet pages<br/>wallet views<br/>[Portfolio.jsx]"]
  node_chain_pages["Chain pages<br/>chain views<br/>[Blockchain.jsx]"]
  node_trading_pages["Trading pages<br/>market views<br/>[Markets.jsx]"]
  node_ops_pages["Ops pages<br/>support views<br/>[Harness.jsx]"]
  node_common_ui["Common UI<br/>shared components<br/>[Header.jsx]"]
  node_wallet_ui["Wallet UI<br/>wallet components<br/>[WalletCard.jsx]"]
  node_chain_ui["Chain UI<br/>blockchain components<br/>[BlockList.jsx]"]
  node_analytic_ui["Analytics UI<br/>table/chart components<br/>[PortfolioChart.jsx]"]
  node_state_contexts["Contexts<br/>react context<br/>[ThemeContext.jsx]"]
  node_chain_hook["Chain hook<br/>data hook<br/>[useBlockchain.js]"]
  node_services_layer["Services<br/>data boundary<br/>[httpClient.js]"]
  node_mock_data[("Mock data<br/>local datasets<br/>[mockBlocks.json]")]
  node_harness_sim["Harness sim<br/>simulation service"]
end

subgraph group_backend["Rust Engine"]
  node_rust_main["Rust app<br/>native binary<br/>[main.rs]"]
  node_rust_cli["CLI<br/>command layer<br/>[cli.rs]"]
  node_rust_consensus["Consensus<br/>chain logic<br/>[consensus.rs]"]
  node_rust_ledger[("Ledger store<br/>file-backed ledger")]
  node_rust_gui["Aux GUI<br/>utility script<br/>[blockchain_gui.py]"]
end

node_app_shell -->|"uses"| node_app_routes
node_app_routes -->|"opens"| node_dashboard_page
node_app_routes -->|"opens"| node_wallet_pages
node_app_routes -->|"opens"| node_chain_pages
node_app_routes -->|"opens"| node_trading_pages
node_app_routes -->|"opens"| node_ops_pages
node_dashboard_page -->|"assembles"| node_common_ui
node_wallet_pages -->|"uses"| node_wallet_ui
node_chain_pages -->|"uses"| node_chain_ui
node_trading_pages -->|"uses"| node_analytic_ui
node_ops_pages -->|"uses"| node_common_ui
node_common_ui -->|"reads"| node_state_contexts
node_wallet_ui -->|"reads"| node_state_contexts
node_chain_ui -->|"reads"| node_chain_hook
node_chain_hook -->|"calls"| node_services_layer
node_services_layer -->|"loads"| node_mock_data
node_services_layer -->|"orchestrates"| node_harness_sim
node_services_layer -.->|"integrates with"| node_rust_main
node_rust_main -->|"exposes"| node_rust_cli
node_rust_main -->|"runs"| node_rust_consensus
node_rust_main -->|"persists to"| node_rust_ledger
node_rust_main -.->|"supports"| node_rust_gui

click node_app_shell "https://github.com/anushka2503769/wallet-ui/blob/main/src/main.jsx"
click node_app_routes "https://github.com/anushka2503769/wallet-ui/blob/main/src/routes.jsx"
click node_dashboard_page "https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Dashboard/Dashboard.jsx"
click node_wallet_pages "https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Portfolio/Portfolio.jsx"
click node_chain_pages "https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Blockchain/Blockchain.jsx"
click node_trading_pages "https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Markets/Markets.jsx"
click node_ops_pages "https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Harness/Harness.jsx"
click node_common_ui "https://github.com/anushka2503769/wallet-ui/blob/main/src/components/common/Header.jsx"
click node_wallet_ui "https://github.com/anushka2503769/wallet-ui/blob/main/src/components/wallet/WalletCard.jsx"
click node_chain_ui "https://github.com/anushka2503769/wallet-ui/blob/main/src/components/blockchain/BlockList.jsx"
click node_analytic_ui "https://github.com/anushka2503769/wallet-ui/blob/main/src/components/charts/PortfolioChart.jsx"
click node_state_contexts "https://github.com/anushka2503769/wallet-ui/blob/main/src/context/ThemeContext.jsx"
click node_chain_hook "https://github.com/anushka2503769/wallet-ui/blob/main/src/hooks/useBlockchain.js"
click node_services_layer "https://github.com/anushka2503769/wallet-ui/blob/main/src/services/api/httpClient.js"
click node_mock_data "https://github.com/anushka2503769/wallet-ui/blob/main/src/data/mockBlocks.json"
click node_harness_sim "https://github.com/anushka2503769/wallet-ui/blob/main/src/services/harness/simulationService.js"
click node_rust_main "https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/src/main.rs"
click node_rust_cli "https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/src/cli.rs"
click node_rust_consensus "https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/src/consensus.rs"
click node_rust_ledger "https://github.com/anushka2503769/wallet-ui/tree/main/rust-blockchain/ledger/CURRENT"
click node_rust_gui "https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/blockchain_gui.py"

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_app_shell,node_app_routes,node_dashboard_page,node_wallet_pages,node_chain_pages,node_trading_pages,node_ops_pages,node_common_ui,node_wallet_ui,node_chain_ui,node_analytic_ui,node_state_contexts,node_chain_hook,node_services_layer,node_mock_data,node_harness_sim toneBlue
class node_rust_main,node_rust_cli,node_rust_consensus,node_rust_ledger,node_rust_gui toneAmber
```

## Components

### React SPA

Browser-based wallet and trading UI built with React and Vite.

- [App shell](https://github.com/anushka2503769/wallet-ui/blob/main/src/main.jsx): React/Vite SPA · Bootstraps the single-page app and global layout. · `src/main.jsx`
- [Routes](https://github.com/anushka2503769/wallet-ui/blob/main/src/routes.jsx): navigation · Maps URLs to product pages. · `src/routes.jsx`
- [Dashboard](https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Dashboard/Dashboard.jsx): wallet page · Overview page for portfolio and activity. · `src/pages/Dashboard/Dashboard.jsx`
- [Wallet pages](https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Portfolio/Portfolio.jsx): wallet views · Portfolio, transactions, and send/receive flows. · `src/pages/Portfolio/Portfolio.jsx`
- [Chain pages](https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Blockchain/Blockchain.jsx): chain views · Blockchain, explorer, validators, and staking screens. · `src/pages/Blockchain/Blockchain.jsx`
- [Trading pages](https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Markets/Markets.jsx): market views · Markets and derivatives trading screens. · `src/pages/Markets/Markets.jsx`
- [Ops pages](https://github.com/anushka2503769/wallet-ui/blob/main/src/pages/Harness/Harness.jsx): support views · Harness, open positions, trade history, and settings. · `src/pages/Harness/Harness.jsx`
- [Common UI](https://github.com/anushka2503769/wallet-ui/blob/main/src/components/common/Header.jsx): shared components · Shell and reusable layout elements. · `src/components/common/Header.jsx`
- [Wallet UI](https://github.com/anushka2503769/wallet-ui/blob/main/src/components/wallet/WalletCard.jsx): wallet components · Wallet cards and transaction entry widgets. · `src/components/wallet/WalletCard.jsx`
- [Chain UI](https://github.com/anushka2503769/wallet-ui/blob/main/src/components/blockchain/BlockList.jsx): blockchain components · Block lists, cards, and network status widgets. · `src/components/blockchain/BlockList.jsx`
- [Analytics UI](https://github.com/anushka2503769/wallet-ui/blob/main/src/components/charts/PortfolioChart.jsx): table/chart components · Tabular and chart-based portfolio and history views. · `src/components/charts/PortfolioChart.jsx`
- [Contexts](https://github.com/anushka2503769/wallet-ui/blob/main/src/context/ThemeContext.jsx): react context · App-wide theme and wallet state. · `src/context/ThemeContext.jsx`
- [Chain hook](https://github.com/anushka2503769/wallet-ui/blob/main/src/hooks/useBlockchain.js): data hook · Shared access point for blockchain state. · `src/hooks/useBlockchain.js`
- [Services](https://github.com/anushka2503769/wallet-ui/blob/main/src/services/api/httpClient.js): data boundary · API, blockchain provider, and harness integration layer. · `src/services/api/httpClient.js`
- [Mock data](https://github.com/anushka2503769/wallet-ui/blob/main/src/data/mockBlocks.json): local datasets · Static JSON fixtures used by the UI. · `src/data/mockBlocks.json`
- [Harness sim](https://github.com/anushka2503769/wallet-ui/blob/main/src/services/harness/simulationService.js): simulation service · Simulation and test harness logic for non-live runs. · `src/services/harness/simulationService.js`

### Rust Engine

Native blockchain simulator and ledger subsystem.

- [Rust app](https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/src/main.rs): native binary · Entry point for the blockchain simulator/backend. · `rust-blockchain/src/main.rs`
- [CLI](https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/src/cli.rs): command layer · Command-line interaction and control. · `rust-blockchain/src/cli.rs`
- [Consensus](https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/src/consensus.rs): chain logic · Consensus and validation logic. · `rust-blockchain/src/consensus.rs`
- [Ledger store](https://github.com/anushka2503769/wallet-ui/tree/main/rust-blockchain/ledger/CURRENT): file-backed ledger · Persistent chain state stored on disk. · `rust-blockchain/ledger/CURRENT`
- [Aux GUI](https://github.com/anushka2503769/wallet-ui/blob/main/rust-blockchain/blockchain_gui.py): utility script · Supplementary GUI or helper entry point. · `rust-blockchain/blockchain_gui.py`

## Connections

- App shell → Routes: uses · Shell renders routed screens.
- Routes → Dashboard: opens · Route dispatch to dashboard.
- Routes → Wallet pages: opens · Route dispatch to wallet views.
- Routes → Chain pages: opens · Route dispatch to chain views.
- Routes → Trading pages: opens · Route dispatch to trading views.
- Routes → Ops pages: opens · Route dispatch to support views.
- Dashboard → Common UI: assembles · Uses shared layout and page chrome.
- Wallet pages → Wallet UI: uses · Wallet screens compose wallet widgets.
- Chain pages → Chain UI: uses · Chain screens compose blockchain widgets.
- Trading pages → Analytics UI: uses · Trading screens lean on tables and charts.
- Ops pages → Common UI: uses · Support views reuse shell components.
- Common UI → Contexts: reads · Shell consumes global theme and wallet state.
- Wallet UI → Contexts: reads · Wallet widgets depend on wallet context.
- Chain UI → Chain hook: reads · Blockchain widgets use shared chain access.
- Chain hook → Services: calls · Hook delegates to service abstractions.
- Services → Mock data: loads · Default data source for local UI flows.
- Services → Harness sim: orchestrates · Harness service coordinates simulation flows.
- Services → Rust app: integrates with · Backend boundary for real chain execution.
- Rust app → CLI: exposes · Native binary includes CLI entry points.
- Rust app → Consensus: runs · Main process drives consensus logic.
- Rust app → Ledger store: persists to · Chain state is stored in file-backed ledger.
- Rust app → Aux GUI: supports · Auxiliary GUI/helper entry point.
