telegram-management-system/marketing-agent/QUICKSTART.md

Quick Start Guide - Telegram Marketing Agent System

Prerequisites

• Docker and Docker Compose installed
• At least 8GB of RAM available
• Telegram API credentials (API ID and API Hash)

🚀 Quick Setup

1. Clone and Navigate

cd telegram-management-system/marketing-agent

2. Configure Environment

# Copy the development environment file
cp .env.development .env

# Edit the .env file and add your Telegram credentials:
# TELEGRAM_API_ID=your-api-id
# TELEGRAM_API_HASH=your-api-hash

3. Start All Services

# Make scripts executable
chmod +x scripts/*.sh

# Start all services
./scripts/start-services.sh

4. Verify System Health

./scripts/health-check.sh

5. Access the Application

• Frontend: http://localhost:3008
• API Gateway: http://localhost:3030
• API Documentation: http://localhost:3030/api-docs

📝 Default Credentials

• Username: admin@example.com
• Password: admin123

🔧 Service Ports

Service	Port	Description
Frontend	3008	Vue.js web interface
API Gateway	3030	Unified API endpoint
Orchestrator	3001	Campaign management
Claude Agent	3002	AI integration
GramJS Adapter	3003	Telegram integration
Safety Guard	3004	Content moderation
Analytics	3005	Data analytics
Compliance	3006	Compliance management
A/B Testing	3007	Experiment management

🛠 Common Commands

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api-gateway

Restart Services

# All services
docker-compose restart

# Specific service
docker-compose restart orchestrator

Stop Services

docker-compose down

Clean Reset

# Stop services and remove volumes
docker-compose down -v

# Start fresh
./scripts/start-services.sh

🚨 Troubleshooting

Service Won't Start

1. Check port conflicts: lsof -i :PORT
2. View logs: docker-compose logs SERVICE_NAME
3. Ensure Docker has enough resources

API Gateway Connection Issues

1. Verify API Gateway is running: curl http://localhost:3030/health
2. Check service discovery: curl http://localhost:3030/health/services
3. Review proxy configuration in services/api-gateway/src/routes/proxy.js

Frontend Can't Connect to API

1. Check browser console for errors
2. Verify API Gateway is accessible
3. Clear browser cache and cookies

Telegram Connection Issues

1. Ensure API credentials are correct in .env
2. Check gramjs-adapter logs: docker-compose logs gramjs-adapter
3. Delete session files and reconnect

📚 Next Steps

1. Connect Telegram Account: Navigate to Settings > Accounts in the web interface
2. Create First Campaign: Go to Campaigns > Create Campaign
3. Configure AI Assistant: Set up Claude API key in Settings
4. Import Contacts: Use the data import feature in Settings

🔐 Security Notes

• Change default credentials immediately
• Update JWT_SECRET in production
• Configure proper CORS origins
• Enable HTTPS for production deployment
• Regularly update dependencies

📞 Support

• Check logs first: docker-compose logs -f
• Review documentation in /docs directory
• Create issues in the project repository

---

Happy Marketing! 🚀