CopperX Payout Bot Architecture#
This document outlines the architecture of the CopperX Payout Bot, explaining how the different components work together to create a seamless user experience.System Overview#
The CopperX Payout Bot is built on a webhook-based architecture that integrates with Telegram's Bot API and the CopperX financial platform. The system is designed to be modular, scalable, and fault-tolerant.Core Components#
1. Webhook Handler#
The entry point for all interactions is the webhook handler in src/bot/webhook.ts. This component:Receives updates from Telegram
Routes them to appropriate handlers
Handles errors gracefully
Returns appropriate responses
2. Command Operations#
Commands are structured in the src/bot/operations/command.operations.ts file. This maps Telegram commands to their handler functions:3. Callback Operations#
Callbacks from inline keyboards are handled by src/bot/operations/callback.operations.ts. This includes a dynamic system for handling callbacks with parameters:4. Services Layer#
The services layer abstracts API interactions:AuthService: Handles authentication with CopperX
WalletService: Manages wallet operations
TransferService: Handles fund transfers
NotificationService: Manages real-time notifications
5. Session Management#
User sessions are managed by the SessionService, which uses Redis for persistence. Each user has a session object that tracks:Current command flow state
Temporary data for multi-step operations
6. Rate Limiting#
The RateLimitService provides protection against abuse by limiting the number of requests per user within a time window. This is implemented using Redis-based counters.Data Flow#
1.
User Input: User sends a command or clicks a button in Telegram
2.
Webhook Processing: Express server receives the update and passes it to the handler
3.
Command/Callback Routing: Update is routed to the appropriate handler
4.
Business Logic: Handler executes business logic, often calling services
5.
API Interaction: Services interact with the CopperX API as needed
6.
Response Generation: Handler prepares and sends a response to the user
7.
Session Update: User session is updated to reflect new state
State Management#
The bot implements a state machine pattern using the UserState enum to track where users are in multi-step flows:Authentication Flow#
1.
User initiates login with /login command
2.
Bot prompts for email address
3.
CopperX API sends OTP to user's email
5.
Bot verifies OTP with CopperX API
6.
On success, session is updated with authentication tokens
7.
KYC status is checked and stored in session
Security Considerations#
Rate Limiting: Prevents abuse
Error Handling: Properly catches and logs errors without exposing sensitive information
Session Management: Securely stores user sessions with expiration
Input Validation: Validates all user inputs before processing
Access Control: Verifies authentication and KYC status before allowing sensitive operations
External Integrations#
Telegram Bot API: For all user interactions
CopperX API: For financial operations
Redis: For session and rate limit storage
Pusher: For real-time notifications
Modified at 2025-03-23 17:04:00
