154 lines
4.7 KiB
Markdown
154 lines
4.7 KiB
Markdown
# 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 |