# SMS Campaign Manager Documentation

SMS Campaign Manager is a Dockerized SMS automation system with Android device integration via Termux API. It provides a web interface for managing campaigns, tracking responses, and viewing analytics.

## Getting Started

New to SMS Campaign Manager? Follow these guides in order:

1. **[Installation Guide](setup/installation.md)** - Complete production setup
2. **[Quick Start](setup/quick-start.md)** - Deploy and verify your installation
3. **[Authentication Setup](setup/authentication.md)** - Configure user login

## Documentation Overview

### Setup

| Guide | Description |
|-------|-------------|
| [Installation Guide](setup/installation.md) | Step-by-step production installation |
| [Quick Start](setup/quick-start.md) | Rapid deployment and testing |
| [Authentication Setup](setup/authentication.md) | User login and session configuration |

### Security

| Guide | Description |
|-------|-------------|
| [Security Setup](security/security-setup.md) | API keys, Docker security, best practices |
| [API Security](security/api-security.md) | API authentication implementation |

### Deployment

| Guide | Description |
|-------|-------------|
| [Deployment Guide](deployment/deployment-guide.md) | Production deployment with Tailscale |

### User Guides

| Guide | Description |
|-------|-------------|
| [User Management](guides/user-management.md) | Creating and managing users |
| [Testing](guides/testing.md) | Verification and testing procedures |
| [Troubleshooting](guides/troubleshooting.md) | Common issues and solutions |

### Development

| Guide | Description |
|-------|-------------|
| [Android Development](development/android-dev-setup.md) | Android device configuration |
| [Termux Flask Setup](development/termux-flask-setup.md) | Termux server configuration |

### Reference

| Guide | Description |
|-------|-------------|
| [API Endpoints](api/endpoints.md) | Complete API reference |
| [Environment Variables](reference/environment-variables.md) | Configuration options |
| [File Structure](reference/files.md) | Project organization |
| [Project Instructions](reference/project-instructions.md) | Development guidelines |

## System Architecture

```
Ubuntu Server (Docker)          Android Device (Termux)
┌─────────────────────┐        ┌─────────────────────┐
│  Flask Web App      │        │  Termux SMS API     │
│  Port 5000          │◄──────►│  Port 5001          │
│                     │        │                     │
│  - Campaign Mgmt    │        │  - SMS Sending      │
│  - Contact Upload   │        │  - Device Status    │
│  - Analytics        │        │  - Response Sync    │
│  - User Auth        │        │                     │
└─────────────────────┘        └─────────────────────┘
         │                              │
         ▼                              ▼
    SQLite Database             Android SMS System
```

## Key Features

**Campaign Management**
- Create and schedule SMS campaigns
- Import contacts from CSV files
- Personalize messages with template variables
- Track delivery and responses

**User Management**
- Web-based login (no browser extensions needed)
- Role-based access control (Admin/User)
- API key authentication for automation
- 24-hour session persistence

**Android Integration**
- Send SMS via Termux API
- Automatic device status monitoring
- Battery and connectivity tracking
- Fallback to ADB if needed

**Security**
- API key authentication
- Session-based web authentication
- Docker container isolation
- Encrypted Tailscale connectivity

## Requirements

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

**Android Device**
- Termux (from F-Droid, not Google Play)
- Termux:API (from F-Droid)
- Tailscale app
- SSH server enabled in Termux

## Quick Links

- **Start Here**: [Installation Guide](setup/installation.md)
- **Having Issues?**: [Troubleshooting](guides/troubleshooting.md)
- **API Reference**: [API Endpoints](api/endpoints.md)
- **Configuration**: [Environment Variables](reference/environment-variables.md)

## Project Structure

```
campaign_connector/
├── src/               # Flask application code
├── android/           # Android Termux servers
├── docs/              # Documentation (this site)
├── scripts/           # Deployment and utility scripts
├── docker/            # Docker configuration
├── data/              # SQLite database (runtime)
├── uploads/           # CSV uploads (runtime)
└── logs/              # Application logs (runtime)
```