🎓 Initial commit: Math2 Platform - Plataforma de Álgebra Lineal PRO
✨ Características: - 45 ejercicios universitarios (Basic → Advanced) - Renderizado LaTeX profesional - IA generativa (Z.ai/DashScope) - Docker 9 servicios - Tests 123/123 pasando - Seguridad enterprise (JWT, XSS, Rate limiting) 🐳 Infraestructura: - Next.js 14 + Node.js 20 - PostgreSQL 15 + Redis 7 - Docker Compose completo - Nginx + SSL ready 📚 Documentación: - 5 informes técnicos completos - README profesional - Scripts de deployment automatizados Estado: Producción lista ✅
This commit is contained in:
Renato
383
backend/TELEGRAM_ARCHITECTURE.md
Normal file
383
backend/TELEGRAM_ARCHITECTURE.md
Normal file
@@ -0,0 +1,383 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user