# 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.