# 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
```bash
# 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
```bash
# 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
```bash
# 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