Key Flows (Deposit, Withdrawal, Payment, Auth)

This page documents the main system flows with flowcharts for learning and operations.

Authentication (Telegram → Gateway)

flowchart LR
  A[Mini App / TWA] -->|Init Data or X-Telegram-Id| B[Gateway]
  B --> C{Validate Telegram}
  C -->|OK| D[Account: Get/Create User]
  D --> E[JWT or Session]
  E --> F[API Access]
  C -->|Fail| G[401 Unauthorized]

Client sends Telegram init data or X-Telegram-Id; Gateway validates and resolves user via Account.
After verification, client receives JWT or session and can call protected endpoints.

Crypto Deposit (Chain → User Balance)

flowchart TD
  A[User receives deposit address] --> B[User sends crypto]
  B --> C[Chain]
  C --> D[Watcher]
  D --> E[Match address → user]
  E --> F[Insert deposit DB]
  F --> G[Ledger credit]
  G --> H[Outbox / NATS]
  H --> I[Bot: Deposit confirmed]

Watcher indexes chain, matches tx to deposit address, persists deposit, credits ledger, publishes event; bot notifies user.

Withdrawal (User → Chain)

flowchart TD
  A[User requests withdrawal] --> B[Gateway]
  B --> C[Wallet: balance check]
  C --> D[Withdrawal service: build tx]
  D --> E[Signer: sign]
  E --> F[Broadcast to chain]
  F --> G[Persist withdrawal record]
  G --> H[Ledger debit]
  H --> I[Notify user]

Gateway receives request; Wallet checks balance; Withdrawal builds and signs tx; Wallet (or RPC) broadcasts; DB and ledger updated; user notified.

Payment (IRT / Fiat)

flowchart TD
  A[User adds card / IBAN] --> B[Gateway → Payment]
  B --> C[Paystar Card-to-IBAN]
  C --> D[Account: store card verification]
  D --> E[User deposits IRT to IBAN]
  E --> F[Statement sync / Payment worker]
  F --> G[Match source_iban / card]
  G --> H[Ledger credit IRT]
  H --> I[Publish wallet.events]
  I --> J[Bot: Deposit confirmed]

Card verification stores IBAN; user deposits to that IBAN; Payment syncs statements, matches by IBAN/card, credits ledger, publishes event, bot notifies.