# urriki1502/wam-fusion-promax architecture

> Architecture diagram of the GitHub repository urriki1502/wam-fusion-promax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urriki1502/wam-fusion-promax
- Repository: https://github.com/urriki1502/wam-fusion-promax

## Overview

WAM Privacy Wallet is an experimental, disposable REGTEST desktop wallet—not a mainnet or production-custody product. Its principal workflow launches an isolated WAM Core, initializes a fresh or same-Mac recovered wallet, scans for balance and history, then requires separate review, signing, and broadcast actions; encrypted backups and recovery preserve anchored state and reservations. The graph includes wallet, custody, scanner, and fee-policy layers alongside the GUI and platform storage. README capabilities identify the workflow; source-index references support internal links, but unsampled implementations and dynamic wiring limit finer detail.

Main entry points: [`src/wam_regtest/wallet_session.py`](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/wallet_session.py) (Wallet session), [`src/wam_regtest/bip39_spend_session.py`](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_spend_session.py) (Payment approvals), [`src/wam_regtest/managed_wallet_checkpoint.py`](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/managed_wallet_checkpoint.py) (Wallet checkpoints), [`src/wam_regtest/wsp_live.py`](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/wsp_live.py) (WSP scanner and signer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Wallet experience"]
  node_fusion["Fusion wallet UI"]
  node_owner_gui["Owner wallet UI<br/>[bip39_owner_gui.py]"]
  node_locale["Wallet languages<br/>[bip39_locale.py]"]
end

subgraph group_wallet["Wallet operations"]
  node_wallet_session["Wallet session<br/>[wallet_session.py]"]
  node_spend_session["Payment approvals"]
  node_payment_state["Payment state<br/>[payment_state.py]"]
  node_fee_policy["Fee policy<br/>[fee_policy.py]"]
  node_fee_rpc["Fee RPC<br/>[fee_rpc.py]"]
  node_wsp["WSP scanner and signer<br/>[wsp_live.py]"]
  node_bip39["BIP39 wallet support<br/>[bip39_12.py]"]
  node_projection["Snapshot projection"]
end

subgraph group_security["Custody and recovery"]
  node_vault[("Encrypted vault<br/>[vault.py]")]
  node_checkpoint["Wallet checkpoints"]
  node_managed_session["Managed sessions"]
  node_custody["Native custody<br/>[custody.py]"]
  node_windows_storage["Windows private storage"]
  node_seed_vault["Seed vault"]
  node_recovery["Wallet recovery<br/>[wallet_recovery.py]"]
end

subgraph group_runtime["Core and network"]
  node_core["Verified Core runtime<br/>[core.py]"]
  node_rpc_scope["Owned RPC scope<br/>[rpc_scope.py]"]
end

node_owner(("Wallet owner"))
node_core_actor(("WAM Core service"))

node_owner -->|"uses"| node_fusion
node_fusion -->|"operates"| node_wallet_session
node_owner_gui -->|"operates"| node_wallet_session
node_wallet_session -->|"starts and verifies"| node_core
node_wallet_session -->|"attests RPC"| node_rpc_scope
node_wallet_session -->|"scans and transacts"| node_wsp
node_wallet_session -->|"persists state"| node_vault
node_wallet_session -->|"secures wallet"| node_custody
node_wallet_session -->|"quotes fees"| node_fee_policy
node_fee_rpc -->|"provides policy inputs"| node_fee_policy
node_wallet_session -->|"tracks payments"| node_payment_state
node_spend_session -->|"coordinates spending"| node_wallet_session
node_spend_session -->|"uses payment state"| node_payment_state
node_spend_session -->|"uses fee policy"| node_fee_policy
node_spend_session -->|"uses signer"| node_wsp
node_bip39 -->|"uses derivation"| node_wsp
node_checkpoint -->|"creates protected storage"| node_custody
node_checkpoint -->|"opens checkpoint vault"| node_vault
node_checkpoint -->|"checks wallet state"| node_wallet_session
node_managed_session -->|"loads checkpoint"| node_checkpoint
node_managed_session -->|"checks recovery"| node_recovery
node_custody -->|"selects native storage"| node_windows_storage
node_seed_vault -->|"uses custody"| node_custody
node_seed_vault -->|"uses vault"| node_vault
node_core -->|"launches local Core"| node_core_actor
node_core -->|"enforces RPC scope"| node_rpc_scope
node_wsp -->|"scans live chain"| node_core_actor
node_wallet_session -.->|"projects snapshots"| node_projection
node_fusion -.->|"uses translations"| node_locale

click node_fusion "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_fusion_gui.py"
click node_owner_gui "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_owner_gui.py"
click node_locale "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_locale.py"
click node_wallet_session "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/wallet_session.py"
click node_spend_session "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_spend_session.py"
click node_payment_state "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/domain/payment_state.py"
click node_fee_policy "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/domain/fee_policy.py"
click node_fee_rpc "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/infrastructure/fee_rpc.py"
click node_wsp "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/wsp_live.py"
click node_bip39 "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_12.py"
click node_projection "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/application/snapshot_projection.py"
click node_vault "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/vault.py"
click node_checkpoint "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/managed_wallet_checkpoint.py"
click node_managed_session "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/managed_wallet_session.py"
click node_custody "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/custody.py"
click node_windows_storage "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/windows_private_storage.py"
click node_seed_vault "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_seed_vault.py"
click node_recovery "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/wallet_recovery.py"
click node_core "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/core.py"
click node_rpc_scope "https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/rpc_scope.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_fusion,node_owner_gui,node_locale toneBlue
class node_wallet_session,node_spend_session,node_payment_state,node_fee_policy,node_fee_rpc,node_wsp,node_bip39,node_projection toneAmber
class node_vault,node_checkpoint,node_managed_session,node_custody,node_windows_storage,node_seed_vault,node_recovery toneMint
class node_core,node_rpc_scope toneRose
class node_owner,node_core_actor toneIndigo
```

## Components

### Wallet experience

- [Fusion wallet UI](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_fusion_gui.py): `src/wam_regtest/bip39_fusion_gui.py`
- [Owner wallet UI](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_owner_gui.py): `src/wam_regtest/bip39_owner_gui.py`
- [Wallet languages](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_locale.py): `src/wam_regtest/bip39_locale.py`

### Wallet operations

- [Wallet session](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/wallet_session.py): `src/wam_regtest/wallet_session.py`
- [Payment approvals](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_spend_session.py): `src/wam_regtest/bip39_spend_session.py`
- [Payment state](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/domain/payment_state.py): `src/wam_regtest/domain/payment_state.py`
- [Fee policy](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/domain/fee_policy.py): `src/wam_regtest/domain/fee_policy.py`
- [Fee RPC](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/infrastructure/fee_rpc.py): `src/wam_regtest/infrastructure/fee_rpc.py`
- [WSP scanner and signer](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/wsp_live.py): `src/wam_regtest/wsp_live.py`
- [BIP39 wallet support](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_12.py): `src/wam_regtest/bip39_12.py`
- [Snapshot projection](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/application/snapshot_projection.py): `src/wam_regtest/application/snapshot_projection.py`

### Custody and recovery

- [Encrypted vault](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/vault.py): `src/wam_regtest/vault.py`
- [Wallet checkpoints](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/managed_wallet_checkpoint.py): `src/wam_regtest/managed_wallet_checkpoint.py`
- [Managed sessions](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/managed_wallet_session.py): `src/wam_regtest/managed_wallet_session.py`
- [Native custody](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/custody.py): `src/wam_regtest/custody.py`
- [Windows private storage](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/windows_private_storage.py): `src/wam_regtest/windows_private_storage.py`
- [Seed vault](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/bip39_seed_vault.py): `src/wam_regtest/bip39_seed_vault.py`
- [Wallet recovery](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/wallet_recovery.py): `src/wam_regtest/wallet_recovery.py`

### Core and network

- [Verified Core runtime](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/core.py): `src/wam_regtest/core.py`
- [Owned RPC scope](https://github.com/urriki1502/wam-fusion-promax/blob/main/src/wam_regtest/rpc_scope.py): `src/wam_regtest/rpc_scope.py`

### Other components

- **Wallet owner**
- **WAM Core service**

## Connections

- Wallet owner → Fusion wallet UI: uses (evidence: `README.md`)
- Fusion wallet UI → Wallet session: operates (evidence: `README.md`)
- Owner wallet UI → Wallet session: operates
- Wallet session → Verified Core runtime: starts and verifies (evidence: `src/wam_regtest/wallet_session.py`)
- Wallet session → Owned RPC scope: attests RPC (evidence: `src/wam_regtest/wallet_session.py`)
- Wallet session → WSP scanner and signer: scans and transacts (evidence: `src/wam_regtest/wallet_session.py`)
- Wallet session → Encrypted vault: persists state (evidence: `src/wam_regtest/wallet_session.py`)
- Wallet session → Native custody: secures wallet (evidence: `src/wam_regtest/wallet_session.py`)
- Wallet session → Fee policy: quotes fees (evidence: `src/wam_regtest/wallet_session.py`)
- Fee RPC → Fee policy: provides policy inputs (evidence: `src/wam_regtest/infrastructure/fee_rpc.py`)
- Wallet session → Payment state: tracks payments (evidence: `src/wam_regtest/wallet_session.py`)
- Payment approvals → Wallet session: coordinates spending (evidence: `src/wam_regtest/bip39_spend_session.py`)
- Payment approvals → Payment state: uses payment state (evidence: `src/wam_regtest/bip39_spend_session.py`)
- Payment approvals → Fee policy: uses fee policy (evidence: `src/wam_regtest/bip39_spend_session.py`)
- Payment approvals → WSP scanner and signer: uses signer (evidence: `src/wam_regtest/bip39_spend_session.py`)
- BIP39 wallet support → WSP scanner and signer: uses derivation (evidence: `src/wam_regtest/bip39_12.py`)
- Wallet checkpoints → Native custody: creates protected storage (evidence: `src/wam_regtest/managed_wallet_checkpoint.py`)
- Wallet checkpoints → Encrypted vault: opens checkpoint vault (evidence: `src/wam_regtest/managed_wallet_checkpoint.py`)
- Wallet checkpoints → Wallet session: checks wallet state (evidence: `src/wam_regtest/managed_wallet_checkpoint.py`)
- Managed sessions → Wallet checkpoints: loads checkpoint (evidence: `src/wam_regtest/managed_wallet_session.py`)
- Managed sessions → Wallet recovery: checks recovery (evidence: `src/wam_regtest/managed_wallet_session.py`)
- Native custody → Windows private storage: selects native storage (evidence: `src/wam_regtest/custody.py`)
- Seed vault → Native custody: uses custody (evidence: `src/wam_regtest/bip39_seed_vault.py`)
- Seed vault → Encrypted vault: uses vault (evidence: `src/wam_regtest/bip39_seed_vault.py`)
- Verified Core runtime → WAM Core service: launches local Core (evidence: `README.md`)
- Verified Core runtime → Owned RPC scope: enforces RPC scope (evidence: `src/wam_regtest/core.py`)
- WSP scanner and signer → WAM Core service: scans live chain (evidence: `src/wam_regtest/wsp_live.py`)
- Wallet session → Snapshot projection: projects snapshots
- Fusion wallet UI → Wallet languages: uses translations (evidence: `src/wam_regtest/bip39_fusion_gui.py`)
