Initial commit: Telegram Management System

Full-stack web application for Telegram management - Frontend: Vue 3 + Vben Admin - Backend: NestJS - Features: User management, group broadcast, statistics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-04 15:37:50 +08:00
commit 237c7802e5
3674 changed files with 525172 additions and 0 deletions
--- a/marketing-agent/docs/architecture/system-architecture.md
+++ b/marketing-agent/docs/architecture/system-architecture.md
@@ -0,0 +1,267 @@
+# 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