# lightcountry/tokenpay architecture

> Architecture diagram of the GitHub repository lightcountry/tokenpay, 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/lightcountry/tokenpay
- Repository: https://github.com/lightcountry/tokenpay

## Overview

TokenPay is a self-hosted blockchain payment service: merchants create payment orders, customers pay to assigned TRON or EVM addresses, background workers reconcile on-chain transfers against pending orders, and completed orders trigger merchant notifications. The README documents dynamic or static addresses, multiple asset families, exchange-rate updates, address collection, and a read-only admin area with manual completion support. Sampled code confirms order creation/checking, chain polling, TRON collection, and admin actions; several service links rely on the README’s documented workflow because their implementations were not sampled.

Main entry points: [`src/TokenPay/Program.cs`](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Program.cs) (Application Host), [`src/TokenPay/Domains/TokenOrders.cs`](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Domains/TokenOrders.cs) (Order Records), [`src/TokenPay/Controllers/HomeController.cs`](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Controllers/HomeController.cs) (Order Endpoints), [`src/TokenPay/BgServices/OrderCheckTRC20Service.cs`](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckTRC20Service.cs) (TRC20 Watcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and Orders"]
  node_program["Application Host<br/>[Program.cs]"]
  node_home["Order Endpoints<br/>[HomeController.cs]"]
  node_admin["Admin Console<br/>[AdminController.cs]"]
end

subgraph group_chains["Chain Monitoring"]
  node_trxworker["TRX Watcher"]
  node_trcworker["TRC20 Watcher"]
  node_evmworker["EVM Watcher"]
  node_ercworker["ERC20 Watcher"]
  node_tronclient["TRON Client"]
end

subgraph group_operations["Operations"]
  node_rateworker["Rate Updater"]
  node_expiry["Order Expiry"]
  node_success["Payment Completion"]
  node_notify["Merchant Callback"]
  node_collection["TRON Collection"]
end

subgraph group_state["Payment State"]
  node_orders[("Order Records<br/>[TokenOrders.cs]")]
  node_wallets[("Payment Wallets<br/>[Tokens.cs]")]
  node_rates[("Rate Records<br/>[TokenRate.cs]")]
end

node_merchant(("Merchant System"))
node_customer(("Customer"))
node_chainapis{{"Blockchain APIs"}}
node_merchantcallback(("Merchant Callback URL"))

node_program -->|"routes requests"| node_home
node_program -->|"routes requests"| node_admin
node_program -->|"starts worker"| node_rateworker
node_program -->|"starts worker"| node_trxworker
node_program -->|"starts worker"| node_trcworker
node_program -->|"starts worker"| node_evmworker
node_program -->|"starts worker"| node_ercworker
node_program -->|"starts worker"| node_expiry
node_program -->|"starts worker"| node_success
node_program -->|"starts worker"| node_notify
node_program -->|"starts worker"| node_collection
node_merchant -->|"creates order"| node_home
node_customer -->|"requests payment"| node_home
node_home -->|"creates and reads"| node_orders
node_home -->|"assigns address"| node_wallets
node_home -->|"uses rates"| node_rates
node_rateworker -->|"updates rates"| node_rates
node_trxworker -->|"reconciles transfers"| node_orders
node_trcworker -->|"reconciles transfers"| node_orders
node_evmworker -->|"reconciles transfers"| node_orders
node_ercworker -->|"reconciles transfers"| node_orders
node_trxworker -->|"polls chain"| node_chainapis
node_trcworker -->|"polls chain"| node_chainapis
node_evmworker -->|"polls chain"| node_chainapis
node_ercworker -->|"polls chain"| node_chainapis
node_trcworker -->|"signals paid"| node_success
node_ercworker -->|"signals paid"| node_success
node_success -->|"dispatches completion"| node_notify
node_notify -->|"sends callback"| node_merchantcallback
node_expiry -->|"expires orders"| node_orders
node_admin -->|"reviews and updates"| node_orders
node_admin -->|"retries callback"| node_notify
node_collection -->|"reads addresses"| node_wallets
node_collection -->|"builds transfers"| node_tronclient
node_tronclient -->|"queries and broadcasts"| node_chainapis

click node_program "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Program.cs"
click node_home "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Controllers/HomeController.cs"
click node_admin "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Controllers/AdminController.cs"
click node_orders "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Domains/TokenOrders.cs"
click node_wallets "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Domains/Tokens.cs"
click node_rates "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Domains/TokenRate.cs"
click node_rateworker "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/UpdateRateService.cs"
click node_trxworker "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckTRXService.cs"
click node_trcworker "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckTRC20Service.cs"
click node_evmworker "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckEVMBaseService.cs"
click node_ercworker "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckEVMERC20Service.cs"
click node_expiry "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderExpiredService.cs"
click node_success "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderPaySuccessService.cs"
click node_notify "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderNotifyService.cs"
click node_collection "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/CollectionTRONService.cs"
click node_tronclient "https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Helper/TronCollectionClient.cs"

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_program,node_home,node_admin toneBlue
class node_trxworker,node_trcworker,node_evmworker,node_ercworker,node_tronclient toneAmber
class node_rateworker,node_expiry,node_success,node_notify,node_collection,node_chainapis toneMint
class node_orders,node_wallets,node_rates toneRose
class node_merchant,node_customer,node_merchantcallback toneIndigo
```

## Components

### Web and Orders

- [Application Host](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Program.cs): `src/TokenPay/Program.cs`
- [Order Endpoints](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Controllers/HomeController.cs): `src/TokenPay/Controllers/HomeController.cs`
- [Admin Console](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Controllers/AdminController.cs): `src/TokenPay/Controllers/AdminController.cs`

### Chain Monitoring

- [TRX Watcher](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckTRXService.cs): `src/TokenPay/BgServices/OrderCheckTRXService.cs`
- [TRC20 Watcher](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckTRC20Service.cs): `src/TokenPay/BgServices/OrderCheckTRC20Service.cs`
- [EVM Watcher](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckEVMBaseService.cs): `src/TokenPay/BgServices/OrderCheckEVMBaseService.cs`
- [ERC20 Watcher](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderCheckEVMERC20Service.cs): `src/TokenPay/BgServices/OrderCheckEVMERC20Service.cs`
- [TRON Client](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Helper/TronCollectionClient.cs): `src/TokenPay/Helper/TronCollectionClient.cs`

### Operations

- [Rate Updater](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/UpdateRateService.cs): `src/TokenPay/BgServices/UpdateRateService.cs`
- [Order Expiry](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderExpiredService.cs): `src/TokenPay/BgServices/OrderExpiredService.cs`
- [Payment Completion](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderPaySuccessService.cs): `src/TokenPay/BgServices/OrderPaySuccessService.cs`
- [Merchant Callback](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/OrderNotifyService.cs): `src/TokenPay/BgServices/OrderNotifyService.cs`
- [TRON Collection](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/BgServices/CollectionTRONService.cs): `src/TokenPay/BgServices/CollectionTRONService.cs`

### Payment State

- [Order Records](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Domains/TokenOrders.cs): `src/TokenPay/Domains/TokenOrders.cs`
- [Payment Wallets](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Domains/Tokens.cs): `src/TokenPay/Domains/Tokens.cs`
- [Rate Records](https://github.com/lightcountry/tokenpay/blob/master/src/TokenPay/Domains/TokenRate.cs): `src/TokenPay/Domains/TokenRate.cs`

### Other components

- **Merchant System**
- **Customer**
- **Blockchain APIs**
- **Merchant Callback URL**

## Connections

- Application Host → Order Endpoints: routes requests
- Application Host → Admin Console: routes requests
- Application Host → Rate Updater: starts worker
- Application Host → TRX Watcher: starts worker
- Application Host → TRC20 Watcher: starts worker
- Application Host → EVM Watcher: starts worker
- Application Host → ERC20 Watcher: starts worker
- Application Host → Order Expiry: starts worker
- Application Host → Payment Completion: starts worker
- Application Host → Merchant Callback: starts worker
- Application Host → TRON Collection: starts worker
- Merchant System → Order Endpoints: creates order
- Customer → Order Endpoints: requests payment
- Order Endpoints → Order Records: creates and reads
- Order Endpoints → Payment Wallets: assigns address
- Order Endpoints → Rate Records: uses rates
- Rate Updater → Rate Records: updates rates
- TRX Watcher → Order Records: reconciles transfers
- TRC20 Watcher → Order Records: reconciles transfers
- EVM Watcher → Order Records: reconciles transfers
- ERC20 Watcher → Order Records: reconciles transfers
- TRX Watcher → Blockchain APIs: polls chain
- TRC20 Watcher → Blockchain APIs: polls chain
- EVM Watcher → Blockchain APIs: polls chain
- ERC20 Watcher → Blockchain APIs: polls chain
- TRC20 Watcher → Payment Completion: signals paid
- ERC20 Watcher → Payment Completion: signals paid
- Payment Completion → Merchant Callback: dispatches completion
- Merchant Callback → Merchant Callback URL: sends callback
- Order Expiry → Order Records: expires orders
- Admin Console → Order Records: reviews and updates
- Admin Console → Merchant Callback: retries callback
- TRON Collection → Payment Wallets: reads addresses
- TRON Collection → TRON Client: builds transfers
- TRON Client → Blockchain APIs: queries and broadcasts