# SMS Campaign Manager

Dockerized SMS automation system with Android device integration via Termux API.

## Features

- **Campaign Management**: Create, schedule, and monitor SMS campaigns
- **Contact Import**: Upload contacts from CSV files with template variables
- **Android Integration**: Send SMS through Termux API with ADB fallback
- **User Authentication**: Web login and API key access
- **Real-time Analytics**: Track delivery status and responses

## Architecture

```
Ubuntu Server (Docker)          Android Device (Termux)
┌─────────────────────┐        ┌─────────────────────┐
│  Flask Web App      │◄──────►│  Termux SMS API     │
│  Port 5000          │        │  Port 5001          │
└─────────────────────┘        └─────────────────────┘
```

## Quick Start

```bash
# 1. Configure environment
cp .env.example .env
nano .env  # Set your Android device IP and credentials

# 2. Generate API keys
python3 src/core/auth.py

# 3. Deploy to Android
./scripts/deploy-android.sh

# 4. Start the application
docker compose up -d

# 5. Open web dashboard
open http://localhost:5000
```

## Requirements

**Ubuntu Server**
- Docker and Docker Compose
- Tailscale (recommended) or local network access

**Android Device**
- Termux (from F-Droid)
- Termux:API (from F-Droid)
- SSH server enabled

## Documentation

Full documentation is available in the [docs/](docs/) directory:

### Getting Started
- [Installation Guide](docs/setup/installation.md) - Complete setup instructions
- [Quick Start](docs/setup/quick-start.md) - Rapid deployment
- [Authentication](docs/setup/authentication.md) - User login configuration

### Configuration
- [Security Setup](docs/security/security-setup.md) - API keys and Docker security
- [Environment Variables](docs/reference/environment-variables.md) - All configuration options

### User Guides
- [User Management](docs/guides/user-management.md) - Managing users and roles
- [Testing Guide](docs/guides/testing.md) - Verification procedures
- [Troubleshooting](docs/guides/troubleshooting.md) - Common issues

### Reference
- [API Endpoints](docs/api/endpoints.md) - Complete API reference
- [Deployment Guide](docs/deployment/deployment-guide.md) - Production deployment

## Project Structure

```
campaign_connector/
├── src/               # Flask application
├── android/           # Termux server scripts
├── docs/              # Documentation
├── scripts/           # Deployment scripts
├── docker/            # Docker configuration
├── data/              # SQLite database (runtime)
├── uploads/           # CSV uploads (runtime)
└── logs/              # Application logs (runtime)
```

## Common Commands

```bash
# Start services
docker compose up -d

# View logs
docker compose logs -f sms-campaign

# Stop services
docker compose down

# Manage users
python3 manage_users.py
```

## Support

For issues:
1. Check [Troubleshooting](docs/guides/troubleshooting.md)
2. Review logs: `docker compose logs`
3. Verify configuration in `.env`

## License

Copyright 2025 Campaign Connector Team