# cyberpokemon/packetpay architecture

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

- Interactive diagram: https://gitdiagram.com/cyberpokemon/packetpay
- Repository: https://github.com/cyberpokemon/packetpay

## Overview

PacketPay is a secure offline-payment relay simulation: a sender creates a payment on a node, which either sends it directly to the Bank or encrypts and relays it over multicast for later delivery. The Bank is the financial authority, handling account checks, payment execution, transaction history, expiry and idempotency. The README documents the main flows and relay behaviors; sampled source confirms the Bank payment controller’s decrypt-then-process calls and the UDP listener’s event dispatch, but does not expose all service wiring.

Main entry points: [`node/src/main/java/com/cyberpokemon/PacketPay/node/node/payment/service/PaymentServiceImpl.java`](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/payment/service/PaymentServiceImpl.java) (Payment service), [`bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/service/PaymentServiceImpl.java`](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/service/PaymentServiceImpl.java) (Payment processing), [`node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/network/UdpMulticastNetworkService.java`](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/network/UdpMulticastNetworkService.java) (UDP multicast), [`bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/controller/PaymentController.java`](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/controller/PaymentController.java) (Bank payment API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node["Sender Node"]
  node_nodeui["Node GUI<br/>[node_gui.py]"]
  node_nodepayment["Node payment API"]
  node_nodepayservice["Payment service"]
  node_connectivity["Connectivity state"]
  node_identity["Node identity"]
  node_identity_store[("Identity store")]
  node_bankclient["Bank client"]
end

subgraph group_relay["Relay Network"]
  node_relayservice["Relay service"]
  node_decision["Relay decision"]
  node_network["UDP multicast"]
  node_relayevent["Packet event"]
end

subgraph group_bank["Bank Services"]
  node_bankapi["Bank payment API"]
  node_payment["Payment processing"]
  node_idempotency["Idempotency"]
  node_accounts["Account services"]
  node_accountdb[("Account store")]
  node_paymentdb[("Payment store")]
  node_txdb[("Transaction state")]
  node_bankui["Bank GUI<br/>[bank_gui.py]"]
end

subgraph group_security["Cryptography"]
  node_nodecrypto["Node encryption"]
  node_bankcrypto["Bank decryption"]
  node_keypair["Bank key pair"]
end

node_user(("Payment user"))
node_peers(("Peer nodes"))

node_user -->|"initiates payment"| node_nodeui
node_nodeui -->|"submits request"| node_nodepayment
node_nodepayment -->|"handles payment"| node_nodepayservice
node_nodepayservice -->|"checks status"| node_connectivity
node_nodepayservice -->|"encrypts request"| node_nodecrypto
node_nodepayservice -->|"sends directly"| node_bankclient
node_nodepayservice -->|"relays offline"| node_relayservice
node_nodepayservice -.->|"uses identity"| node_identity
node_identity -->|"reads and writes"| node_identity_store
node_bankclient -->|"calls Bank"| node_bankapi
node_relayservice -->|"chooses action"| node_decision
node_relayservice -->|"dispatches packet"| node_network
node_network -->|"multicasts packet"| node_peers
node_peers -.->|"forwards packet"| node_network
node_network -->|"publishes event"| node_relayevent
node_bankapi -->|"decrypts request"| node_bankcrypto
node_bankapi -->|"processes payment"| node_payment
node_bankcrypto -->|"uses private key"| node_keypair
node_payment -->|"tracks transaction"| node_idempotency
node_payment -->|"verifies and updates"| node_accounts
node_payment -->|"stores payment"| node_paymentdb
node_idempotency -->|"stores status"| node_txdb
node_accounts -->|"reads and writes"| node_accountdb
node_bankui -.->|"uses Bank API"| node_bankapi

click node_nodeui "https://github.com/cyberpokemon/packetpay/blob/main/frontend/node_gui.py"
click node_nodepayment "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/payment/controller/NodePaymentController.java"
click node_nodepayservice "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/payment/service/PaymentServiceImpl.java"
click node_connectivity "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/connectivity/service/ConnectivityServiceImpl.java"
click node_identity "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/identity/service/IdentityServiceImpl.java"
click node_identity_store "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/identity/store/InMemoryIdentityStore.java"
click node_bankclient "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/client/BankClientImpl.java"
click node_nodecrypto "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/crypto/CryptoServiceImpl.java"
click node_relayservice "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/service/RelayServiceImpl.java"
click node_decision "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/service/RelayDecisionEngineImpl.java"
click node_network "https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/network/UdpMulticastNetworkService.java"
click node_bankapi "https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/controller/PaymentController.java"
click node_bankcrypto "https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/crypto/service/CryptoServiceImpl.java"
click node_keypair "https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/crypto/service/KeyPairServiceImpl.java"
click node_payment "https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/service/PaymentServiceImpl.java"
click node_idempotency "https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/idempotency/service/IdempotencyServiceImpl.java"
click node_accountdb "https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/account/repository/AccountRepository.java"
click node_paymentdb "https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/repository/PaymentRepository.java"
click node_txdb "https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/idempotency/repository/ProcessedTransactionRepository.java"
click node_bankui "https://github.com/cyberpokemon/packetpay/blob/main/frontend/bank_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_nodeui,node_nodepayment,node_nodepayservice,node_connectivity,node_identity,node_identity_store,node_bankclient,node_user toneBlue
class node_relayservice,node_decision,node_network,node_relayevent toneAmber
class node_bankapi,node_payment,node_idempotency,node_accounts,node_accountdb,node_paymentdb,node_txdb,node_bankui toneMint
class node_nodecrypto,node_bankcrypto,node_keypair toneRose
class node_peers toneIndigo
```

## Components

### Sender Node

- [Node GUI](https://github.com/cyberpokemon/packetpay/blob/main/frontend/node_gui.py): `frontend/node_gui.py`
- [Node payment API](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/payment/controller/NodePaymentController.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/payment/controller/NodePaymentController.java`
- [Payment service](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/payment/service/PaymentServiceImpl.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/payment/service/PaymentServiceImpl.java`
- [Connectivity state](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/connectivity/service/ConnectivityServiceImpl.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/connectivity/service/ConnectivityServiceImpl.java`
- [Node identity](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/identity/service/IdentityServiceImpl.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/identity/service/IdentityServiceImpl.java`
- [Identity store](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/identity/store/InMemoryIdentityStore.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/identity/store/InMemoryIdentityStore.java`
- [Bank client](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/client/BankClientImpl.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/client/BankClientImpl.java`

### Relay Network

- [Relay service](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/service/RelayServiceImpl.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/service/RelayServiceImpl.java`
- [Relay decision](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/service/RelayDecisionEngineImpl.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/service/RelayDecisionEngineImpl.java`
- [UDP multicast](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/network/UdpMulticastNetworkService.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/relay/network/UdpMulticastNetworkService.java`
- **Packet event**

### Bank Services

- [Bank payment API](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/controller/PaymentController.java): `bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/controller/PaymentController.java`
- [Payment processing](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/service/PaymentServiceImpl.java): `bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/service/PaymentServiceImpl.java`
- [Idempotency](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/idempotency/service/IdempotencyServiceImpl.java): `bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/idempotency/service/IdempotencyServiceImpl.java`
- **Account services**
- [Account store](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/account/repository/AccountRepository.java): `bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/account/repository/AccountRepository.java`
- [Payment store](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/repository/PaymentRepository.java): `bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/payment/repository/PaymentRepository.java`
- [Transaction state](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/idempotency/repository/ProcessedTransactionRepository.java): `bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/idempotency/repository/ProcessedTransactionRepository.java`
- [Bank GUI](https://github.com/cyberpokemon/packetpay/blob/main/frontend/bank_gui.py): `frontend/bank_gui.py`

### Cryptography

- [Node encryption](https://github.com/cyberpokemon/packetpay/blob/main/node/src/main/java/com/cyberpokemon/PacketPay/node/node/crypto/CryptoServiceImpl.java): `node/src/main/java/com/cyberpokemon/PacketPay/node/node/crypto/CryptoServiceImpl.java`
- [Bank decryption](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/crypto/service/CryptoServiceImpl.java): `bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/crypto/service/CryptoServiceImpl.java`
- [Bank key pair](https://github.com/cyberpokemon/packetpay/blob/main/bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/crypto/service/KeyPairServiceImpl.java): `bank/src/main/java/com/cyberpokemon/PacketPay/bank/bank/crypto/service/KeyPairServiceImpl.java`

### Other components

- **Payment user**
- **Peer nodes**

## Connections

- Payment user → Node GUI: initiates payment
- Node GUI → Node payment API: submits request
- Node payment API → Payment service: handles payment
- Payment service → Connectivity state: checks status
- Payment service → Node encryption: encrypts request
- Payment service → Bank client: sends directly
- Payment service → Relay service: relays offline
- Payment service → Node identity: uses identity
- Node identity → Identity store: reads and writes
- Bank client → Bank payment API: calls Bank
- Relay service → Relay decision: chooses action
- Relay service → UDP multicast: dispatches packet
- UDP multicast → Peer nodes: multicasts packet
- Peer nodes → UDP multicast: forwards packet
- UDP multicast → Packet event: publishes event
- Bank payment API → Bank decryption: decrypts request
- Bank payment API → Payment processing: processes payment
- Bank decryption → Bank key pair: uses private key
- Payment processing → Idempotency: tracks transaction
- Payment processing → Account services: verifies and updates
- Payment processing → Payment store: stores payment
- Idempotency → Transaction state: stores status
- Account services → Account store: reads and writes
- Bank GUI → Bank payment API: uses Bank API