# 1227cwx/hdupay architecture

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

- Interactive diagram: https://gitdiagram.com/1227cwx/hdupay
- Repository: https://github.com/1227cwx/hdupay

## Overview

HDupay is a stablecoin payment platform: a payer receives an EVM deposit address, pays a USDC/USDT order, and sees on-chain confirmation progress. Merchants can create and check orders through OpenAPI or the EasyPay-compatible entry point; administrators manage wallets, networks, RPC, rates, and collections. The graph preserves these documented capabilities while showing only wiring supported by the sampled controllers and README; several subsystem links are documented rather than verified in unsampled service code.

Main entry points: [`app/service/DepositService.php`](https://github.com/1227cwx/hdupay/blob/main/app/service/DepositService.php) (Deposit orders), [`app/service`](https://github.com/1227cwx/hdupay/tree/main/app/service) (Admin business services), [`app/model`](https://github.com/1227cwx/hdupay/tree/main/app/model) (Business data models), [`app/service/FiatRateService.php`](https://github.com/1227cwx/hdupay/blob/main/app/service/FiatRateService.php) (Fiat conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User and API entry points"]
  node_paymentui["Payment UI<br/>[Pay.vue]"]
  node_openapi["OpenAPI endpoint"]
  node_epay["EasyPay endpoint"]
  node_depositctl["Deposit endpoint"]
end

subgraph group_orders["Payments and orders"]
  node_deposit["Deposit orders<br/>[DepositService.php]"]
  node_easypay["EasyPay compatibility<br/>[EasyPayService.php]"]
  node_rates["Fiat conversion"]
  node_openapisvc["API authentication<br/>[OpenApiService.php]"]
  node_payorders[("Order and deposit state<br/>[DepositOrder.php]")]
end

subgraph group_chain["Wallet and chain operations"]
  node_addresspool["Address allocation"]
  node_wallet["HD wallet operations<br/>[WalletService.php]"]
  node_monitor["EVM log monitoring"]
  node_rpc["RPC configuration and calls<br/>[EvmRpcService.php]"]
  node_collection["Asset collection"]
end

subgraph group_admin["Administration"]
  node_adminui["Admin dashboard UI"]
  node_adminctl["Admin endpoints"]
  node_adminservices["Admin business services"]
  node_models[("Business data models")]
end

subgraph group_runtime["Background runtime"]
  node_depositworker["Deposit monitor process"]
  node_taskworker["Task queue worker"]
  node_rateworker["Rate refresh process"]
end

node_payer(("Payer"))
node_merchant(("Merchant client"))
node_adminuser(("Administrator"))
node_rpcprovider(("EVM RPC provider"))
node_coingecko(("CoinGecko"))
node_mysql[("MySQL")]
node_merchantcallback(("Merchant callback receiver"))

node_payer -->|"opens payment"| node_paymentui
node_paymentui -->|"requests payment data"| node_depositctl
node_depositctl -->|"creates or queries"| node_deposit
node_deposit -->|"converts fiat"| node_rates
node_deposit -->|"allocates address"| node_addresspool
node_deposit -->|"records order"| node_payorders
node_merchant -->|"calls API"| node_openapi
node_openapi -->|"authenticates and handles"| node_openapisvc
node_openapisvc -->|"creates or checks"| node_deposit
node_merchant -->|"submits payment"| node_epay
node_epay -->|"handles request"| node_easypay
node_easypay -->|"creates order"| node_deposit
node_easypay -->|"returns payment link"| node_paymentui
node_depositworker -->|"runs scans"| node_monitor
node_monitor -->|"requests chain logs"| node_rpc
node_rpc -->|"sends RPC requests"| node_rpcprovider
node_monitor -->|"updates confirmations"| node_payorders
node_taskworker -->|"processes tasks"| node_collection
node_collection -->|"uses chain access"| node_rpc
node_rateworker -->|"refreshes rates"| node_rates
node_rates -->|"fetches prices"| node_coingecko
node_adminuser -->|"uses dashboard"| node_adminui
node_adminui -->|"calls management APIs"| node_adminctl
node_adminctl -->|"delegates operations"| node_adminservices
node_adminservices -->|"manages wallets"| node_wallet
node_adminservices -->|"manages collections"| node_collection
node_adminservices -->|"configures RPC"| node_rpc
node_adminservices -->|"manages rates"| node_rates
node_adminservices -->|"reads and writes"| node_models
node_deposit -->|"reads and writes"| node_models
node_monitor -->|"reads and writes"| node_models
node_collection -->|"reads and writes"| node_models
node_rpc -->|"reads configuration"| node_models
node_rates -->|"reads and writes"| node_models
node_openapisvc -.->|"dispatches callbacks"| node_merchantcallback

click node_paymentui "https://github.com/1227cwx/hdupay/blob/main/web/src/pages/Pay.vue"
click node_openapi "https://github.com/1227cwx/hdupay/blob/main/app/controller/OpenApiController.php"
click node_epay "https://github.com/1227cwx/hdupay/blob/main/app/controller/EasyPayController.php"
click node_depositctl "https://github.com/1227cwx/hdupay/blob/main/app/controller/DepositController.php"
click node_deposit "https://github.com/1227cwx/hdupay/blob/main/app/service/DepositService.php"
click node_easypay "https://github.com/1227cwx/hdupay/blob/main/app/service/EasyPayService.php"
click node_rates "https://github.com/1227cwx/hdupay/blob/main/app/service/FiatRateService.php"
click node_openapisvc "https://github.com/1227cwx/hdupay/blob/main/app/service/OpenApiService.php"
click node_payorders "https://github.com/1227cwx/hdupay/blob/main/app/model/DepositOrder.php"
click node_addresspool "https://github.com/1227cwx/hdupay/blob/main/app/service/AddressPoolService.php"
click node_wallet "https://github.com/1227cwx/hdupay/blob/main/app/service/WalletService.php"
click node_monitor "https://github.com/1227cwx/hdupay/blob/main/app/service/EvmMonitorService.php"
click node_rpc "https://github.com/1227cwx/hdupay/blob/main/app/service/EvmRpcService.php"
click node_collection "https://github.com/1227cwx/hdupay/blob/main/app/service/CollectionService.php"
click node_adminui "https://github.com/1227cwx/hdupay/tree/main/web/src/pages"
click node_adminctl "https://github.com/1227cwx/hdupay/tree/main/app/controller"
click node_adminservices "https://github.com/1227cwx/hdupay/tree/main/app/service"
click node_models "https://github.com/1227cwx/hdupay/tree/main/app/model"
click node_depositworker "https://github.com/1227cwx/hdupay/blob/main/app/process/EvmDepositMonitor.php"
click node_taskworker "https://github.com/1227cwx/hdupay/blob/main/app/process/EvmTaskQueueWorker.php"
click node_rateworker "https://github.com/1227cwx/hdupay/blob/main/app/process/RateRefreshWorker.php"

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_paymentui,node_openapi,node_epay,node_depositctl,node_merchant toneBlue
class node_deposit,node_easypay,node_rates,node_openapisvc,node_payorders,node_mysql toneAmber
class node_addresspool,node_wallet,node_monitor,node_rpc,node_collection toneMint
class node_adminui,node_adminctl,node_adminservices,node_models toneRose
class node_depositworker,node_taskworker,node_rateworker,node_payer,node_adminuser,node_rpcprovider,node_coingecko,node_merchantcallback toneIndigo
```

## Components

### User and API entry points

- [Payment UI](https://github.com/1227cwx/hdupay/blob/main/web/src/pages/Pay.vue): `web/src/pages/Pay.vue`
- [OpenAPI endpoint](https://github.com/1227cwx/hdupay/blob/main/app/controller/OpenApiController.php): `app/controller/OpenApiController.php`
- [EasyPay endpoint](https://github.com/1227cwx/hdupay/blob/main/app/controller/EasyPayController.php): `app/controller/EasyPayController.php`
- [Deposit endpoint](https://github.com/1227cwx/hdupay/blob/main/app/controller/DepositController.php): `app/controller/DepositController.php`

### Payments and orders

- [Deposit orders](https://github.com/1227cwx/hdupay/blob/main/app/service/DepositService.php): `app/service/DepositService.php`
- [EasyPay compatibility](https://github.com/1227cwx/hdupay/blob/main/app/service/EasyPayService.php): `app/service/EasyPayService.php`
- [Fiat conversion](https://github.com/1227cwx/hdupay/blob/main/app/service/FiatRateService.php): `app/service/FiatRateService.php`
- [API authentication](https://github.com/1227cwx/hdupay/blob/main/app/service/OpenApiService.php): `app/service/OpenApiService.php`
- [Order and deposit state](https://github.com/1227cwx/hdupay/blob/main/app/model/DepositOrder.php): `app/model/DepositOrder.php`

### Wallet and chain operations

- [Address allocation](https://github.com/1227cwx/hdupay/blob/main/app/service/AddressPoolService.php): `app/service/AddressPoolService.php`
- [HD wallet operations](https://github.com/1227cwx/hdupay/blob/main/app/service/WalletService.php): `app/service/WalletService.php`
- [EVM log monitoring](https://github.com/1227cwx/hdupay/blob/main/app/service/EvmMonitorService.php): `app/service/EvmMonitorService.php`
- [RPC configuration and calls](https://github.com/1227cwx/hdupay/blob/main/app/service/EvmRpcService.php): `app/service/EvmRpcService.php`
- [Asset collection](https://github.com/1227cwx/hdupay/blob/main/app/service/CollectionService.php): `app/service/CollectionService.php`

### Administration

- [Admin dashboard UI](https://github.com/1227cwx/hdupay/tree/main/web/src/pages): `web/src/pages`
- [Admin endpoints](https://github.com/1227cwx/hdupay/tree/main/app/controller): `app/controller`
- [Admin business services](https://github.com/1227cwx/hdupay/tree/main/app/service): `app/service`
- [Business data models](https://github.com/1227cwx/hdupay/tree/main/app/model): `app/model`

### Background runtime

- [Deposit monitor process](https://github.com/1227cwx/hdupay/blob/main/app/process/EvmDepositMonitor.php): `app/process/EvmDepositMonitor.php`
- [Task queue worker](https://github.com/1227cwx/hdupay/blob/main/app/process/EvmTaskQueueWorker.php): `app/process/EvmTaskQueueWorker.php`
- [Rate refresh process](https://github.com/1227cwx/hdupay/blob/main/app/process/RateRefreshWorker.php): `app/process/RateRefreshWorker.php`

### Other components

- **Payer**
- **Merchant client**
- **Administrator**
- **EVM RPC provider**
- **CoinGecko**
- **MySQL**
- **Merchant callback receiver**

## Connections

- Payer → Payment UI: opens payment
- Payment UI → Deposit endpoint: requests payment data
- Deposit endpoint → Deposit orders: creates or queries
- Deposit orders → Fiat conversion: converts fiat
- Deposit orders → Address allocation: allocates address
- Deposit orders → Order and deposit state: records order
- Merchant client → OpenAPI endpoint: calls API
- OpenAPI endpoint → API authentication: authenticates and handles
- API authentication → Deposit orders: creates or checks
- Merchant client → EasyPay endpoint: submits payment
- EasyPay endpoint → EasyPay compatibility: handles request
- EasyPay compatibility → Deposit orders: creates order
- EasyPay compatibility → Payment UI: returns payment link
- Deposit monitor process → EVM log monitoring: runs scans
- EVM log monitoring → RPC configuration and calls: requests chain logs
- RPC configuration and calls → EVM RPC provider: sends RPC requests
- EVM log monitoring → Order and deposit state: updates confirmations
- Task queue worker → Asset collection: processes tasks
- Asset collection → RPC configuration and calls: uses chain access
- Rate refresh process → Fiat conversion: refreshes rates
- Fiat conversion → CoinGecko: fetches prices
- Administrator → Admin dashboard UI: uses dashboard
- Admin dashboard UI → Admin endpoints: calls management APIs
- Admin endpoints → Admin business services: delegates operations
- Admin business services → HD wallet operations: manages wallets
- Admin business services → Asset collection: manages collections
- Admin business services → RPC configuration and calls: configures RPC
- Admin business services → Fiat conversion: manages rates
- Admin business services → Business data models: reads and writes
- Deposit orders → Business data models: reads and writes
- EVM log monitoring → Business data models: reads and writes
- Asset collection → Business data models: reads and writes
- RPC configuration and calls → Business data models: reads configuration
- Fiat conversion → Business data models: reads and writes
- API authentication → Merchant callback receiver: dispatches callbacks