# bitpolito/silent-payments architecture

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

- Interactive diagram: https://gitdiagram.com/bitpolito/silent-payments
- Repository: https://github.com/bitpolito/silent-payments

## Overview

Silent Payments Educational PoC teaches BIP-352 through a guided sender/receiver simulation, reference-vector checks, and address-generation tools. Users enter through the React app, run the walkthrough or generate a random/vanity address, and receive simulated results; nothing is broadcast. Flask exposes the API, Python implements protocol and reference behavior, and Rust accelerates vanity searches. Studio and privacy labs are additional educational branches. Some backend routes and UI features are documented but not fully sampled, so their links are included only where the README or excerpts establish them.

Main entry points: [`src/App.jsx`](https://github.com/bitpolito/silent-payments/blob/main/src/App.jsx) (App navigation), [`api/index.py`](https://github.com/bitpolito/silent-payments/blob/main/api/index.py) (HTTP routes), [`native/vanity/src/engine.rs`](https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/engine.rs) (Search engine), [`api/core/receive.py`](https://github.com/bitpolito/silent-payments/blob/main/api/core/receive.py) (Payment scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React learning UI"]
  node_app["App navigation<br/>[App.jsx]"]
  node_walkthrough["Payment walkthrough<br/>[PaymentFlow.jsx]"]
  node_flow_view["Flow presentation<br/>[FlowPanels.jsx]"]
  node_address_ui["Address generation<br/>[GenerateAddr.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_backend["Flask API"]
  node_flask["HTTP routes<br/>[index.py]"]
  node_reference["Reference cases<br/>[reference.py]"]
end

subgraph group_protocol["BIP-352 protocol"]
  node_sender["Payment sending<br/>[send.py]"]
  node_receiver["Payment scanning<br/>[receive.py]"]
  node_experiments["Protocol experiments<br/>[experiments.py]"]
  node_crypto["Curve and Schnorr<br/>[schnorr_lib.py]"]
  node_key_hardening["Key validation<br/>[hardened_keys.py]"]
  node_address_encoding["Address encoding<br/>[segwit_addr.py]"]
end

subgraph group_vanity["Vanity generation"]
  node_vanity_service["Vanity service<br/>[vanity_python.py]"]
  node_rust_engine["Search engine<br/>[engine.rs]"]
  node_rust_address["Address encoder<br/>[address.rs]"]
  node_rust_matcher["Pattern matcher<br/>[matcher.rs]"]
  node_rust_generator["Key generation<br/>[generator.rs]"]
end

subgraph group_education["Experiments"]
  node_studio["Studio tools<br/>[Studio.jsx]"]
  node_privacy["Privacy lab<br/>[PrivacyLab.jsx]"]
end

node_user(("Learner"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_walkthrough
node_app -->|"opens"| node_address_ui
node_app -->|"routes to"| node_studio
node_app -->|"routes to"| node_privacy
node_walkthrough -->|"renders"| node_flow_view
node_walkthrough -->|"requests results"| node_api_client
node_address_ui -->|"requests addresses"| node_api_client
node_api_client -->|"calls API"| node_flask
node_flask -->|"dispatches"| node_sender
node_flask -->|"dispatches"| node_receiver
node_flask -->|"dispatches"| node_experiments
node_flask -->|"loads cases"| node_reference
node_sender -->|"uses"| node_crypto
node_receiver -->|"uses"| node_crypto
node_receiver -->|"validates keys"| node_key_hardening
node_experiments -->|"uses"| node_sender
node_experiments -->|"uses"| node_receiver
node_address_ui -->|"requests search"| node_vanity_service
node_vanity_service -->|"runs subprocess"| node_rust_engine
node_rust_engine -->|"generates keys"| node_rust_generator
node_rust_engine -->|"encodes address"| node_rust_address
node_rust_engine -->|"tests pattern"| node_rust_matcher

click node_app "https://github.com/bitpolito/silent-payments/blob/main/src/App.jsx"
click node_walkthrough "https://github.com/bitpolito/silent-payments/blob/main/src/scenes/PaymentFlow.jsx"
click node_flow_view "https://github.com/bitpolito/silent-payments/blob/main/src/components/flow/FlowPanels.jsx"
click node_address_ui "https://github.com/bitpolito/silent-payments/blob/main/src/scenes/GenerateAddr.jsx"
click node_api_client "https://github.com/bitpolito/silent-payments/blob/main/src/utils/api.js"
click node_studio "https://github.com/bitpolito/silent-payments/blob/main/src/features/studio/Studio.jsx"
click node_privacy "https://github.com/bitpolito/silent-payments/blob/main/src/features/privacy/PrivacyLab.jsx"
click node_flask "https://github.com/bitpolito/silent-payments/blob/main/api/index.py"
click node_sender "https://github.com/bitpolito/silent-payments/blob/main/api/core/send.py"
click node_receiver "https://github.com/bitpolito/silent-payments/blob/main/api/core/receive.py"
click node_experiments "https://github.com/bitpolito/silent-payments/blob/main/api/core/experiments.py"
click node_crypto "https://github.com/bitpolito/silent-payments/blob/main/api/core/utils/schnorr_lib.py"
click node_key_hardening "https://github.com/bitpolito/silent-payments/blob/main/api/core/utils/hardened_keys.py"
click node_address_encoding "https://github.com/bitpolito/silent-payments/blob/main/api/core/utils/segwit_addr.py"
click node_reference "https://github.com/bitpolito/silent-payments/blob/main/api/core/reference.py"
click node_vanity_service "https://github.com/bitpolito/silent-payments/blob/main/api/core/utils/vanity_python.py"
click node_rust_engine "https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/engine.rs"
click node_rust_address "https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/address.rs"
click node_rust_matcher "https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/matcher.rs"
click node_rust_generator "https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/generator.rs"

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,node_walkthrough,node_flow_view,node_address_ui,node_api_client toneBlue
class node_flask,node_reference toneAmber
class node_sender,node_receiver,node_experiments,node_crypto,node_key_hardening,node_address_encoding toneMint
class node_vanity_service,node_rust_engine,node_rust_address,node_rust_matcher,node_rust_generator toneRose
class node_studio,node_privacy,node_user toneIndigo
```

## Components

### React learning UI

- [App navigation](https://github.com/bitpolito/silent-payments/blob/main/src/App.jsx): `src/App.jsx`
- [Payment walkthrough](https://github.com/bitpolito/silent-payments/blob/main/src/scenes/PaymentFlow.jsx): `src/scenes/PaymentFlow.jsx`
- [Flow presentation](https://github.com/bitpolito/silent-payments/blob/main/src/components/flow/FlowPanels.jsx): `src/components/flow/FlowPanels.jsx`
- [Address generation](https://github.com/bitpolito/silent-payments/blob/main/src/scenes/GenerateAddr.jsx): `src/scenes/GenerateAddr.jsx`
- [API client](https://github.com/bitpolito/silent-payments/blob/main/src/utils/api.js): `src/utils/api.js`

### Flask API

- [HTTP routes](https://github.com/bitpolito/silent-payments/blob/main/api/index.py): `api/index.py`
- [Reference cases](https://github.com/bitpolito/silent-payments/blob/main/api/core/reference.py): `api/core/reference.py`

### BIP-352 protocol

- [Payment sending](https://github.com/bitpolito/silent-payments/blob/main/api/core/send.py): `api/core/send.py`
- [Payment scanning](https://github.com/bitpolito/silent-payments/blob/main/api/core/receive.py): `api/core/receive.py`
- [Protocol experiments](https://github.com/bitpolito/silent-payments/blob/main/api/core/experiments.py): `api/core/experiments.py`
- [Curve and Schnorr](https://github.com/bitpolito/silent-payments/blob/main/api/core/utils/schnorr_lib.py): `api/core/utils/schnorr_lib.py`
- [Key validation](https://github.com/bitpolito/silent-payments/blob/main/api/core/utils/hardened_keys.py): `api/core/utils/hardened_keys.py`
- [Address encoding](https://github.com/bitpolito/silent-payments/blob/main/api/core/utils/segwit_addr.py): `api/core/utils/segwit_addr.py`

### Vanity generation

- [Vanity service](https://github.com/bitpolito/silent-payments/blob/main/api/core/utils/vanity_python.py): `api/core/utils/vanity_python.py`
- [Search engine](https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/engine.rs): `native/vanity/src/engine.rs`
- [Address encoder](https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/address.rs): `native/vanity/src/address.rs`
- [Pattern matcher](https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/matcher.rs): `native/vanity/src/matcher.rs`
- [Key generation](https://github.com/bitpolito/silent-payments/blob/main/native/vanity/src/generator.rs): `native/vanity/src/generator.rs`

### Experiments

- [Studio tools](https://github.com/bitpolito/silent-payments/blob/main/src/features/studio/Studio.jsx): `src/features/studio/Studio.jsx`
- [Privacy lab](https://github.com/bitpolito/silent-payments/blob/main/src/features/privacy/PrivacyLab.jsx): `src/features/privacy/PrivacyLab.jsx`

### Other components

- **Learner**

## Connections

- Learner → App navigation: uses (evidence: `src/App.jsx`)
- App navigation → Payment walkthrough: routes to (evidence: `src/App.jsx`)
- App navigation → Address generation: opens (evidence: `src/App.jsx`)
- App navigation → Studio tools: routes to (evidence: `src/App.jsx`)
- App navigation → Privacy lab: routes to (evidence: `src/App.jsx`)
- Payment walkthrough → Flow presentation: renders (evidence: `src/scenes/PaymentFlow.jsx`)
- Payment walkthrough → API client: requests results (evidence: `src/scenes/PaymentFlow.jsx`)
- Address generation → API client: requests addresses (evidence: `src/scenes/GenerateAddr.jsx`)
- API client → HTTP routes: calls API (evidence: `README.md`)
- HTTP routes → Payment sending: dispatches (evidence: `api/index.py`)
- HTTP routes → Payment scanning: dispatches (evidence: `api/index.py`)
- HTTP routes → Protocol experiments: dispatches (evidence: `api/index.py`)
- HTTP routes → Reference cases: loads cases (evidence: `api/index.py`)
- Payment sending → Curve and Schnorr: uses (evidence: `api/core/experiments.py`)
- Payment scanning → Curve and Schnorr: uses (evidence: `api/core/receive.py`)
- Payment scanning → Key validation: validates keys (evidence: `api/core/receive.py`)
- Protocol experiments → Payment sending: uses (evidence: `api/core/experiments.py`)
- Protocol experiments → Payment scanning: uses (evidence: `api/core/experiments.py`)
- Address generation → Vanity service: requests search (evidence: `README.md`)
- Vanity service → Search engine: runs subprocess (evidence: `api/core/utils/vanity_python.py`)
- Search engine → Key generation: generates keys (evidence: `native/vanity/src/engine.rs`)
- Search engine → Address encoder: encodes address (evidence: `native/vanity/src/engine.rs`)
- Search engine → Pattern matcher: tests pattern (evidence: `native/vanity/src/engine.rs`)