237c7802e5
Some checks failed
Deploy / deploy (push) Has been cancelled
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>
231 lines
5.1 KiB
Markdown
231 lines
5.1 KiB
Markdown
# Claude Code × Telegram (gramJS) Marketing Intelligence Agent
|
||
|
||
## 🚀 Overview
|
||
|
||
A comprehensive marketing intelligence system that combines Claude AI with Telegram automation for intelligent campaign management. The system provides full-chain automation from goal setting to strategy execution, with human-in-the-loop controls for high-risk decisions.
|
||
|
||
## 🏗️ Architecture
|
||
|
||
### Core Components
|
||
|
||
1. **Orchestrator Service**
|
||
- Task scheduling and state management
|
||
- Redis-based task queue
|
||
- State machine workflow engine
|
||
- Task dependency management
|
||
|
||
2. **Claude Agent**
|
||
- Function calling integration
|
||
- Prompt template management
|
||
- Context and conversation history
|
||
- Multi-model support
|
||
|
||
3. **gramJS Adapter**
|
||
- Telegram API integration
|
||
- Account pool management
|
||
- Message automation tools
|
||
- Event handling
|
||
|
||
4. **Safety Guard**
|
||
- Rate limiting and compliance
|
||
- Content filtering
|
||
- Account health monitoring
|
||
- Telegram ToS compliance
|
||
|
||
5. **Analytics Service**
|
||
- Real-time event tracking
|
||
- Funnel analysis
|
||
- User segmentation
|
||
- ROI calculation
|
||
|
||
6. **A/B Testing Engine**
|
||
- Multi-armed bandit
|
||
- Bayesian optimization
|
||
- Dynamic traffic allocation
|
||
- Experiment management
|
||
|
||
## 🛠️ Tech Stack
|
||
|
||
### Backend
|
||
- **Language**: Node.js (ES6+)
|
||
- **Framework**: Hapi.js
|
||
- **Database**: PostgreSQL (main), MongoDB (events), Redis (cache/queue)
|
||
- **Message Queue**: RabbitMQ
|
||
- **Search**: Elasticsearch
|
||
|
||
### Infrastructure
|
||
- **Container**: Docker
|
||
- **Orchestration**: Kubernetes
|
||
- **Monitoring**: Prometheus + Grafana
|
||
- **Tracing**: OpenTelemetry
|
||
- **API Gateway**: Kong/Nginx
|
||
|
||
### AI/ML
|
||
- **LLM**: Claude API
|
||
- **Vector DB**: Pinecone/Weaviate
|
||
- **ML Framework**: TensorFlow.js
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
marketing-agent/
|
||
├── services/
|
||
│ ├── orchestrator/ # Task orchestration service
|
||
│ ├── claude-agent/ # Claude AI integration
|
||
│ ├── gramjs-adapter/ # Telegram automation
|
||
│ ├── safety-guard/ # Compliance and safety
|
||
│ ├── analytics/ # Analytics engine
|
||
│ ├── ab-testing/ # A/B testing service
|
||
│ └── api-gateway/ # API gateway
|
||
├── shared/
|
||
│ ├── models/ # Shared data models
|
||
│ ├── utils/ # Common utilities
|
||
│ ├── config/ # Configuration
|
||
│ └── types/ # TypeScript types
|
||
├── infrastructure/
|
||
│ ├── docker/ # Docker configs
|
||
│ ├── k8s/ # Kubernetes manifests
|
||
│ ├── terraform/ # Infrastructure as code
|
||
│ └── scripts/ # Deployment scripts
|
||
└── docs/
|
||
├── api/ # API documentation
|
||
├── architecture/ # Architecture diagrams
|
||
└── guides/ # User guides
|
||
```
|
||
|
||
## 🚦 Getting Started
|
||
|
||
### Prerequisites
|
||
- Node.js 18+
|
||
- Docker & Docker Compose
|
||
- PostgreSQL 14+
|
||
- Redis 7+
|
||
- MongoDB 5+
|
||
|
||
### Installation
|
||
|
||
```bash
|
||
# Clone repository
|
||
git clone <repository-url>
|
||
cd marketing-agent
|
||
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Setup environment
|
||
cp .env.example .env
|
||
|
||
# Start services
|
||
docker-compose up -d
|
||
|
||
# Run migrations
|
||
npm run migrate
|
||
|
||
# Start development
|
||
npm run dev
|
||
```
|
||
|
||
## 🔧 Configuration
|
||
|
||
### Environment Variables
|
||
```env
|
||
# Claude API
|
||
CLAUDE_API_KEY=your_api_key
|
||
CLAUDE_MODEL=claude-3-opus-20240229
|
||
|
||
# Database
|
||
POSTGRES_URL=postgresql://user:pass@localhost:5432/marketing
|
||
MONGODB_URL=mongodb://localhost:27017/events
|
||
REDIS_URL=redis://localhost:6379
|
||
|
||
# Telegram
|
||
TELEGRAM_API_ID=your_api_id
|
||
TELEGRAM_API_HASH=your_api_hash
|
||
|
||
# Services
|
||
RABBITMQ_URL=amqp://localhost:5672
|
||
ELASTICSEARCH_URL=http://localhost:9200
|
||
```
|
||
|
||
## 📋 Features
|
||
|
||
### Campaign Management
|
||
- Goal-driven campaign creation
|
||
- Multi-channel orchestration
|
||
- Budget management
|
||
- Performance tracking
|
||
|
||
### AI-Powered Intelligence
|
||
- Strategy generation
|
||
- Content optimization
|
||
- Audience targeting
|
||
- Predictive analytics
|
||
|
||
### Safety & Compliance
|
||
- GDPR/CCPA compliance
|
||
- Rate limiting
|
||
- Content moderation
|
||
- Audit logging
|
||
|
||
### Human-in-the-Loop
|
||
- Approval workflows
|
||
- Risk assessment
|
||
- Manual override
|
||
- Quality control
|
||
|
||
## 🧪 Testing
|
||
|
||
```bash
|
||
# Unit tests
|
||
npm run test
|
||
|
||
# Integration tests
|
||
npm run test:integration
|
||
|
||
# E2E tests
|
||
npm run test:e2e
|
||
|
||
# Coverage report
|
||
npm run test:coverage
|
||
```
|
||
|
||
## 📊 Monitoring
|
||
|
||
- **Metrics**: Prometheus endpoints at `/metrics`
|
||
- **Health**: Health checks at `/health`
|
||
- **Logs**: Centralized logging via ELK stack
|
||
- **Tracing**: Distributed tracing with Jaeger
|
||
|
||
## 🚀 Deployment
|
||
|
||
### Development
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
### Production
|
||
```bash
|
||
# Build containers
|
||
npm run build:docker
|
||
|
||
# Deploy to Kubernetes
|
||
npm run deploy:k8s
|
||
|
||
# Run migrations
|
||
npm run migrate:prod
|
||
```
|
||
|
||
## 📖 Documentation
|
||
|
||
- [API Reference](docs/api/README.md)
|
||
- [Architecture Guide](docs/architecture/README.md)
|
||
- [User Manual](docs/guides/user-manual.md)
|
||
- [Developer Guide](docs/guides/developer.md)
|
||
|
||
## 🤝 Contributing
|
||
|
||
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
|
||
|
||
## 📄 License
|
||
|
||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |