telegram-management-system/marketing-agent/docs/architecture/system-architecture.md

System Architecture - Marketing Intelligence Agent

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                                 Admin Frontend                               │
│                         (React + TypeScript + Ant Design)                    │
└─────────────────────────────────────┬───────────────────────────────────────┘
                                      │
                            ┌─────────┴──────────┐
                            │   API Gateway      │
                            │   (Nginx/Kong)     │
                            └─────────┬──────────┘
                                      │
        ┌─────────────────────────────┼─────────────────────────────┐
        │                             │                             │
┌───────┴────────┐           ┌────────┴────────┐          ┌────────┴────────┐
│  Orchestrator  │           │  Claude Agent   │          │ gramJS Adapter  │
│    Service     │◄─────────►│    Service      │◄────────►│    Service      │
└───────┬────────┘           └────────┬────────┘          └────────┬────────┘
        │                             │                             │
        │                    ┌────────┴────────┐                   │
        │                    │  Safety Guard   │                   │
        │                    │    Service      │◄──────────────────┘
        │                    └────────┬────────┘
        │                             │
┌───────┴────────┐           ┌────────┴────────┐          ┌─────────────────┐
│   Analytics    │           │   A/B Testing   │          │   Compliance    │
│    Service     │◄─────────►│    Service      │◄────────►│     Guard       │
└────────────────┘           └─────────────────┘          └─────────────────┘
        │                             │                             │
        └─────────────────────────────┼─────────────────────────────┘
                                      │
                ┌─────────────────────┼──────────────────────┐
                │                     │                      │
        ┌───────┴────────┐   ┌───────┴────────┐   ┌────────┴────────┐
        │   PostgreSQL   │   │    MongoDB     │   │     Redis       │
        │   (Main DB)    │   │   (Events)     │   │  (Cache/Queue)  │
        └────────────────┘   └────────────────┘   └─────────────────┘

Service Descriptions

1. API Gateway (Port 8000)

• Purpose: Central entry point for all API requests
• Technology: Nginx or Kong
• Features:
  • Request routing
  • Authentication
  • Rate limiting
  • Load balancing
  • SSL termination

2. Orchestrator Service (Port 3001)

• Purpose: Task scheduling and workflow management
• Key Components:
  • Task Queue Manager (BullMQ)
  • State Machine Engine (XState)
  • Task Scheduler
  • Workflow Engine
• Database: PostgreSQL for task persistence

3. Claude Agent Service (Port 3002)

• Purpose: AI-powered decision making and content generation
• Key Components:
  • Claude API Integration
  • Function Calling Handler
  • Prompt Template Engine
  • Context Manager
  • Token Usage Tracker
• Integration: Anthropic Claude API

4. gramJS Adapter Service (Port 3003)

• Purpose: Telegram automation and messaging
• Key Components:
  • Connection Pool Manager
  • Session Manager
  • Message Tools (send, create, invite, etc.)
  • Event Listener
  • FloodWait Handler
• Integration: Telegram API via gramJS

5. Safety Guard Service (Port 3004)

• Purpose: Compliance and safety enforcement
• Key Components:
  • Rate Limiter
  • Content Filter
  • Keyword Blacklist
  • PII Scanner
  • ToS Compliance Checker
  • Account Health Monitor

6. Analytics Service (Port 3005)

• Purpose: Data collection and analysis
• Key Components:
  • Event Collector
  • Real-time Aggregator
  • Funnel Analyzer
  • User Segmentation
  • ROI Calculator
• Database: MongoDB for event storage

7. A/B Testing Service (Port 3006)

• Purpose: Experiment management and optimization
• Key Components:
  • Experiment Engine
  • Traffic Splitter
  • Multi-Armed Bandit
  • Bayesian Optimizer
  • Statistical Calculator

8. Compliance Guard Service (Port 3007)

• Purpose: Legal compliance and data protection
• Key Components:
  • GDPR Compliance
  • CCPA Compliance
  • Data Privacy Scanner
  • Audit Logger
  • Consent Manager

Data Flow

Campaign Creation Flow

1. User → Admin UI → API Gateway
2. API Gateway → Orchestrator Service
3. Orchestrator → Claude Agent (Strategy Generation)
4. Claude Agent → Safety Guard (Content Validation)
5. Safety Guard → Orchestrator (Approved/Rejected)
6. Orchestrator → Campaign Database

Message Sending Flow

1. Orchestrator → Task Queue
2. Task Worker → gramJS Adapter
3. gramJS Adapter → Safety Guard (Pre-check)
4. Safety Guard → gramJS Adapter (Approved)
5. gramJS Adapter → Telegram API
6. Result → Analytics Service
7. Analytics → Event Store

Human-in-the-Loop Flow

1. High-risk Task → Escalation Engine
2. Escalation → Human Review Queue
3. Admin UI → Review Interface
4. Human Decision → Orchestrator
5. Orchestrator → Continue/Abort Task

Infrastructure Components

Message Queue (RabbitMQ)

• Task distribution
• Service communication
• Event broadcasting
• Dead letter queues

Cache Layer (Redis)

• Session storage
• Rate limiting counters
• Temporary data
• Task queues (BullMQ)

Search Engine (Elasticsearch)

• Log aggregation
• Full-text search
• Analytics queries
• Audit trail search

Monitoring Stack

• Prometheus: Metrics collection
• Grafana: Visualization
• Jaeger: Distributed tracing
• ELK Stack: Log management

Security Architecture

Authentication & Authorization

• JWT-based authentication
• Role-based access control (RBAC)
• API key management
• OAuth2 integration

Data Protection

• End-to-end encryption
• At-rest encryption
• TLS/SSL for transit
• Key rotation

Network Security

• VPC isolation
• Security groups
• WAF protection
• DDoS mitigation

Scalability Considerations

Horizontal Scaling

• Stateless services
• Load balancer distribution
• Database read replicas
• Cache clustering

Vertical Scaling

• Resource monitoring
• Auto-scaling groups
• Performance tuning
• Database optimization

High Availability

• Multi-AZ deployment
• Failover mechanisms
• Health checks
• Backup strategies

Deployment Architecture

Container Orchestration

Kubernetes Cluster:
  - Namespace: marketing-agent
  - Services: 8 microservices
  - Ingress: NGINX controller
  - Storage: PersistentVolumes
  - ConfigMaps: Environment configs
  - Secrets: Sensitive data

CI/CD Pipeline

1. Code Push → GitHub
2. GitHub Actions → Build & Test
3. Docker Build → Container Registry
4. Kubernetes Deploy → Staging
5. Integration Tests → Validation
6. Blue-Green Deploy → Production

Development Guidelines

Service Communication

• RESTful APIs for synchronous calls
• RabbitMQ for asynchronous messaging
• gRPC for high-performance internal communication

Error Handling

• Circuit breaker pattern
• Retry with exponential backoff
• Dead letter queues
• Graceful degradation

Logging & Monitoring

• Structured logging (JSON)
• Correlation IDs
• Distributed tracing
• Custom metrics

Testing Strategy

• Unit tests (>80% coverage)
• Integration tests
• End-to-end tests
• Performance tests
• Security tests