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
```yaml
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