# 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.
