# Telegram Notifications Module - Architecture Diagram ## System Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ Math Platform Backend │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐│ │ │ Application Modules ││ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ │ │ User │ │ Exercise │ │ Progress │ │ Ranking │ ││ │ │ │ Module │ │ Module │ │ Module │ │ Module │ ││ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ ││ │ │ │ │ │ │ ││ │ │ └─────────────┴─────────────┴─────────────┘ ││ │ │ │ ││ │ │ ▼ ││ │ │ ┌───────────────────────────┐ ││ │ │ │ Notification Service │ ││ │ │ │ - sendNotification() │ ││ │ │ │ - notifyNewUser() │ ││ │ │ │ - notifySystemError() │ ││ │ │ │ - notifyModuleCompleted()│ ││ │ │ └─────────────┬─────────────┘ ││ │ │ │ ││ │ └────────────────────────────┼──────────────────────────────────────┘┘ │ │ │ ▼ │ ┌────────────────────────────────────────────────────────────────────┐│ │ │ Notification Layer ││ │ │ ││ │ │ ┌──────────────────────────────────────────────────────────────┐ ││ │ │ │ Message Templates (templates/) │ ││ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ ││ │ │ │ │ Alert │ │ Progress │ │ Achievement │ │ ││ │ │ │ │ Templates │ │ Templates │ │ Templates │ │ ││ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ ││ │ │ │ │ ││ │ │ │ - System Notifications - User Registration │ ││ │ │ │ - Error Notifications - Exercise Completion │ ││ │ │ │ - Security Alerts - Module Completion │ ││ │ │ │ - Performance Metrics - Achievements │ ││ │ │ └──────────────────────────────────────────────────────────────┘ ││ │ │ │ ││ │ │ ▼ ││ │ │ ┌──────────────────────────────────────────────────────────────┐ ││ │ │ │ Telegram Client (telegram.client.ts) │ ││ │ │ │ │ ││ │ │ │ - sendMessage() - sendPhoto() - sendDocument() │ ││ │ │ │ - getMe() - healthCheck() - Error Handling │ ││ │ │ │ │ ││ │ │ │ Axios HTTP Client with Retry Logic │ ││ │ │ └──────────────────────────────────────────────────────────────┘ ││ │ └──────────────────────────────┬───────────────────────────────────┘┘ │ │ │ ▼ │ ┌────────────────────────────────────────────────────────────────────┐│ │ │ Queue & Worker Layer ││ │ │ ││ │ │ ┌──────────────────────────────────────────────────────────────┐ ││ │ │ │ Bull Queue (notification-sender.worker.ts) │ ││ │ │ │ │ ││ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ ││ │ │ │ │ Queue │ │ Worker │ │ Retry │ │ ││ │ │ │ │ Management │ │ Processor │ │ Logic │ │ ││ │ │ │ └────────────┘ └────────────┘ └────────────┘ │ ││ │ │ │ │ ││ │ │ │ - Job Priority - Rate Limiting - Auto Cleanup │ ││ │ │ │ - Concurrency - Exponential Backoff │ ││ │ │ └──────────────────────────────────────────────────────────────┘ ││ │ └──────────────────────────────┬───────────────────────────────────┘┘ │ │ └───────────────────────────────────┼───────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ External Services │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ │ │ │ │ Redis Queue │ │ Telegram API │ │ │ │ │ │ │ │ │ │ - Job Storage │ │ - Bot API │ │ │ │ - State Management │ │ - Message Delivery │ │ │ │ - Retry Tracking │ │ - Webhooks (optional)│ │ │ │ │ │ │ │ │ └──────────────────────┘ └──────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────┐ │ │ │ Admin Telegram │ │ Chat │ │ │ │ - Notifications │ │ - Alerts │ │ - Reports │ │ │ └─────────────────────┘ ``` ## Data Flow ### 1. Notification Creation Flow ``` User Action │ ▼ Module Event (e.g., User Registration) │ ▼ Notification Service │ ├─→ Create Notification in Database │ (status: PENDING) │ ├─→ Format Message (Templates) │ - HTML formatting │ - Data sanitization │ - Emoji addition │ └─→ Queue for Processing (Bull Queue + Redis) ``` ### 2. Notification Processing Flow ``` Worker Process │ ├─→ Get Job from Queue │ (Priority-based) │ ├─→ Update Attempt Count │ ├─→ Send via Telegram Client │ │ │ ├─→ Success? │ │ │ │ │ ├─→ Yes: Mark as SENT │ │ │ - Update DB │ │ │ - Log success │ │ │ - Remove from queue │ │ │ │ │ └─→ No: Handle Error │ │ - Check retry limit │ │ - Exponential backoff │ │ - Requeue or mark FAILED │ │ │ └─→ HTTP Request │ (Axios with retry) │ └─→ Next Job ``` ### 3. Error Handling Flow ``` Error Occurs │ ▼ Error Type Detection │ ├─→ Rate Limit (429)? │ └─→ Wait retry_after seconds │ └─→ Retry │ ├─→ Client Error (400, 403)? │ └─→ Log and mark FAILED │ └─→ Don't retry │ ├─→ Server Error (500, 502)? │ └─→ Exponential backoff │ └─→ Retry up to limit │ └─→ Network Error? └─→ Exponential backoff └─→ Retry up to limit ``` ## Component Details ### 1. Configuration (config/telegram.ts) **Responsibilities:** - Bot token management - Admin chat ID storage - API endpoint configuration - Priority filtering - Validation **Key Functions:** - `getConfig()` - Get current configuration - `getBotToken()` - Get bot token - `getAdminChatId()` - Get admin chat ID - `shouldSendByPriority()` - Check priority filter - `healthCheck()` - Validate configuration ### 2. Telegram Client (telegram/telegram.client.ts) **Responsibilities:** - HTTP communication with Telegram API - Request retry logic - Error handling and mapping - Message formatting **Key Functions:** - `sendMessage()` - Send text message - `sendPhoto()` - Send photo - `sendDocument()` - Send document - `getMe()` - Get bot info - `healthCheck()` - Test connection **Error Handling:** - 429: Rate limiting (wait and retry) - 401: Invalid token (don't retry) - 403: Bot blocked (don't retry) - 400: Bad request (don't retry) - 500+: Server errors (retry with backoff) ### 3. Templates (telegram/templates/) **Alert Template:** - System notifications - Error alerts - Daily summaries - Security alerts **Progress Template:** - Exercise completion - Module completion - Streak updates - Progress summaries **Achievement Template:** - Badge unlocks - Ranking milestones - Top 10 entries - Achievement summaries ### 4. Notification Service (notification.service.ts) **Responsibilities:** - Business logic for notifications - Queue management - Statistics tracking - Convenience methods **Key Functions:** - `sendNotification()` - Generic notification sender - `notifyNewUser()` - User registration alert - `notifySystemError()` - Error reporting - `notifyModuleCompleted()` - Module completion - `notifyTop10Entry()` - Top 10 achievement - `getStatistics()` - Get notification stats ### 5. Worker (workers/notification-sender.worker.ts) **Responsibilities:** - Background job processing - Queue management - Retry logic - Job cleanup **Key Functions:** - `queueNotification()` - Add job to queue - `retryFailedNotifications()` - Retry failed jobs - `getQueueStats()` - Get queue statistics - `pauseQueue()` / `resumeQueue()` - Queue control **Queue Configuration:** - Concurrency: 3 jobs - Rate limit: 20 messages/minute - Max retries: 3 - Backoff: Exponential - Cleanup: 24h (completed), 7d (failed) ## Security Considerations ### 1. No End-User Exposure - Telegram completely hidden from users - Bot token never exposed in API - Admin chat ID is server-side only ### 2. Input Sanitization - HTML escaping in templates - Length limits on messages - Truncation of long content ### 3. Rate Limiting - Built-in rate limiting (20/min) - Respects Telegram API limits - Queue prevents spam ### 4. Error Filtering - Sensitive data not in errors - Stack traces truncated - User data anonymized ## Performance Optimizations ### 1. Async Processing - All notifications queued - Non-blocking for main thread - Background worker processing ### 2. Connection Pooling - Axios instance reuse - HTTP/2 support - Keep-alive connections ### 3. Efficient Queue - Redis for fast operations - Job prioritization - Batch processing support ### 4. Smart Retry - Exponential backoff - Respect retry-after header - Skip non-retryable errors ## Monitoring & Observability ### 1. Logging - Structured logging with Winston - Correlation IDs for tracking - Debug level for development ### 2. Metrics - Queue depth - Processing time - Success/failure rates - Rate limit hits ### 3. Health Checks - Telegram connection - Queue status - Worker status - Redis connection ### 4. Statistics - Total notifications - By type - By status - Today's counts ## Scalability Considerations ### Horizontal Scaling - Worker can run on multiple servers - Redis shared queue - No local state ### Vertical Scaling - Configurable concurrency - Adjustable rate limits - Memory-efficient queue ### Load Handling - Queue absorbs spikes - Priority ensures important messages first - Rate limiting prevents overload ## Summary The Telegram Notifications Module provides: 1. **Complete Implementation**: All components in place 2. **Production Ready**: Error handling, retry, monitoring 3. **Well Architected**: Separation of concerns, modular design 4. **Scalable**: Async processing, queue-based 5. **Secure**: No user exposure, input sanitization 6. **Maintainable**: Clear structure, good documentation 7. **Testable**: Test scripts, health checks 8. **Observable**: Logging, metrics, statistics The module is ready for production use and can handle high notification loads while maintaining reliability and performance.