campaign_connector/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SMS Campaign Manager - A Dockerized SMS automation system with Android device integration via Termux API and ADB. The system manages SMS campaigns, tracks responses, and provides real-time analytics through a Flask web interface.

Key Commands

Development

# Start the application using Docker Compose
docker-compose up -d

# Start using convenience script
./run.sh start

# View logs
docker-compose logs -f sms-campaign

# Stop services
docker-compose down

# Rebuild after code changes
docker-compose build && docker-compose up -d

# Access container shell for debugging
docker-compose exec sms-campaign bash

Testing

# Run test script (if available)
python test_refactoring.py

# Test phone connectivity
curl http://localhost:5000/api/phone/status

# Test SMS functionality
curl -X POST http://localhost:5000/api/sms/test \
  -H "Content-Type: application/json" \
  -d '{"phone":"YOUR_NUMBER","message":"Test message"}'

# Test Termux API health
curl http://10.0.0.193:5001/health

Android Device Management

# Deploy Android services
scp -P 8022 android/*.sh android-dev@10.0.0.193:~/bin/
scp -P 8022 android/*.py android-dev@10.0.0.193:~/projects/sms-campaign-manager/

# Start all Android services
ssh android-dev "~/bin/start-all-services.sh"

# Check service status
ssh android-dev "~/bin/sms-service.sh status"

# Auto-connect phone via ADB
./scripts/auto.sh

Architecture

Three-Tier System Architecture

Ubuntu Homelab (Port 5000) → Flask Web Application
    ↓ HTTP API calls
Android SMS API Server (Port 5001) → Termux SMS API
    ↓ 
Android Monitor Dashboard (Port 5000) → Device monitoring

Core Service Components

1. Flask Application (src/app.py)

   • Main web application orchestrator
   • Manages campaign creation, scheduling, and monitoring
   • Coordinates with Android services via HTTP APIs

2. Database Layer (src/database/)

   • SQLite database at data/campaign.db
   • Manages campaigns, contacts, messages, and responses
   • DatabaseManager handles initialization and migrations
   • DatabaseHelper provides query abstractions

3. SMS Services (src/services/sms/)

   • SMSConnectionManager: Manages dual connection (Termux API + ADB fallback)
   • SMSSender: Handles message sending with retry logic
   • Automatic failover between Termux (fast) and ADB (reliable)

4. Campaign Services (src/services/campaign/)

   • CampaignManager: Campaign lifecycle management
   • CampaignExecutor: Message sending orchestration
   • MessageUtils: Template processing and variable substitution

5. Background Services (src/services/background/)

   • PhoneMonitor: Device connectivity and health monitoring
   • ResponseSyncService: SMS reply synchronization

6. API Routes (src/routes/api/)

   • Campaign management endpoints
   • SMS sending and testing endpoints
   • File upload and CSV processing
   • Analytics and reporting

Configuration Management

Configuration is centralized in src/core/config.py:

• Phone IP and ports (ADB, Termux API)
• SMS retry settings (max retries, delays)
• Flask settings (secret key, upload limits)
• Database and file paths

Environment variables are loaded from .env file (see .env.example template).

Key Design Patterns

1. Dual Connection Strategy: Primary Termux API with automatic ADB fallback
2. Retry Mechanism: Exponential backoff for SMS sending failures
3. Modular Architecture: Clear separation of concerns across services
4. Factory Pattern: create_app() for Flask application initialization
5. Service Layer: Business logic separated from routes/controllers

Dependencies

Python 3.x with key packages:

• Flask 3.0.0 - Web framework
• flask-socketio 5.3.5 - WebSocket support
• requests 2.31.0 - HTTP client
• aiohttp 3.9.1 - Async HTTP support

Install with: pip install -r src/requirements.txt

File Structure Notes

• src/ - Main application code (Flask app, services, routes)
• android/ - Android-side Python servers (Termux API server, monitoring app)
• data/ - SQLite database (created at runtime)
• uploads/ - CSV contact uploads
• logs/ - Application logs
• docker/ - Docker configuration files
• scripts/ - Shell automation scripts

Important Considerations

• The system requires an Android device with Termux and Termux:API installed
• Device IP is configured in .env (default: 10.0.0.193)
• Uses network_mode: host in Docker for ADB connectivity
• Requires privileged mode for USB device access
• SMS retry logic uses exponential backoff (2s, 4s, 8s)
• WebSocket service provides real-time updates to web interface