math2-platform/backend/TELEGRAM_ARCHITECTURE.md

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.