# CCAR Alert Portal 🚨

A lightweight, multi-threaded Desktop Alert Dispatching & Roster Management System built with Python and Tkinter. The **CCAR Alert Portal** is engineered for emergency communications, volunteer corps (e.g., ARES, RACES, SKYWARN), and operational teams needing immediate or scheduled mass dispatching across Email and SMS Gateways with real-time US English spell checking.

---

## 📋 Table of Contents
- [Key Features](#-key-features)
- [Architecture & Design](#-architecture--design)
- [Prerequisites & Dependencies](#-prerequisites--dependencies)
- [Installation & Quickstart](#-installation--quickstart)
- [Configuration](#-configuration)
- [Usage Guide](#-usage-guide)
  - [1. Send Dispatch](#1-send-dispatch)
  - [2. Manage Roster](#2-manage-roster)
  - [3. SMTP Setup](#3-smtp-setup)
- [US Spell Check System](#-us-spell-check-system)
- [Google Contacts CSV Import](#-google-contacts-csv-import)
- [Database Structure](#-database-structure)
- [License](#-license)

---

## ✨ Key Features

- **Multi-Channel Dispatching:** Send emergency messages simultaneously via standard SMTP Email and cellular SMS Gateways (e.g., `number@vtext.com`).
- **Flexible Targeting Modes:**
  - **Broadcast All:** Deploy alerts to the full active contact roster.
  - **Group / Tag Filter:** Filter operators dynamically by operational tags (`ARES`, `RACES`, `SKYWARN`, `LEADER`, etc.).
  - **Individual Operator:** Fast autocomplete search to message individual volunteers.
- **Immediate & Scheduled Transmissions:**
  - Send instantly or queue alerts for future dates and times.
  - Interactive **Queue Manager** to inspect pending dispatches and cancel queued timers on demand.
- **US English Spell Check & Radio Glossary:**
  - Real-time debounced live-syntax underlining (red underline).
  - Right-click contextual suggestions for misspelled words.
  - Interactive modal dialog for batch spell check.
  - Pre-loaded domain dictionary for amateur radio acronyms (`ARES`, `RACES`, `SKYWARN`, `callsign`, `repeater`, `simplex`, `VHF`, `UHF`, `QRZ`, etc.).
- **Roster & Contact Management:**
  - Add, edit, filter, and delete operators with fine-grained communication channel toggles (Email Ok / Text Ok).
  - Bulk import contacts from standard Google Contacts CSV exports with automatic tag parsing.
- **Zero Heavy Infrastructure:** Persistent local JSON storage (`contacts_db.json`) requiring no database servers.

---

## 🏗 Architecture & Design

```
ccar-alert-portal/
├── dispatch.py          # Core application UI, threading, and SMTP engine
├── contacts_db.json     # Local JSON database (auto-generated on first run)
├── requirements.txt     # Python dependencies
└── README.md            # Documentation
```

### Threading Model
- **Non-blocking UI:** Immediate and scheduled alert transmissions run inside background worker threads (`threading.Timer` / `threading.Thread`) to keep the Tkinter event loop responsive during SMTP socket connections and batch transmissions.

---

## 📦 Prerequisites & Dependencies

- **Python:** `3.8+` (with `tkinter` support enabled)
- **Required Libraries:**
  - [`pyspellchecker`](https://pypi.org/project/pyspellchecker/) (US English dictionary checking & suggestions)

---

## 🚀 Installation & Quickstart

1. **Clone the repository:**
   ```bash
   git clone https://github.com/your-org/ccar-alert-portal.git
   cd ccar-alert-portal
   ```

2. **Create a virtual environment (recommended):**
   ```bash
   python3 -m venv venv
   source venv/bin/activate    # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies:**
   ```bash
   pip install pyspellchecker
   ```

4. **Launch the application:**
   ```bash
   python dispatch.py
   ```

---

## ⚙ Configuration

Navigate to the **SMTP Setup** tab upon first launch to configure your outgoing mail server:

| Field | Description | Example (Gmail) | Example (Custom SMTP) |
| :--- | :--- | :--- | :--- |
| **SMTP Server** | Outgoing mail server hostname | `smtp.gmail.com` | `mail.yourdomain.org` |
| **Port** | SMTP Port (Supports STARTTLS & SSL) | `587` (TLS) or `465` (SSL) | `587` |
| **Sender Email**| Authenticated account email address | `operator@gmail.com` | `dispatch@yourdomain.org` |
| **App Password**| SMTP account password or App Password | `xxxx xxxx xxxx xxxx` | `SecretPassword123` |

> **Note for Gmail Users:** Use an [App Password](https://myaccount.google.com/apppasswords) rather than your personal Google account password if 2-Factor Authentication is enabled.

---

## 📖 Usage Guide

### 1. Send Dispatch
1. **Choose Recipient Targeting Mode:**
   - `All Roster Members`: Broadcast to entire roster.
   - `By Group Tag Filter`: Select a specific active group (e.g. `SKYWARN`).
   - `Individual Operator`: Search and select a single volunteer by callsign, name, or email.
2. **Select Channels:** Toggle *Send via Email* and/or *Send via Text (SMS)*.
3. **Set Transmission Timing:**
   - Select `Send Immediately` or `Schedule Deployment` (provide `MM-DD-YY` and 24-hour `HH:MM`).
4. **Draft Alert Message:** Type plain text or basic HTML tags (`<b>`, `<i>`, `<br>`).
5. **Spell Check:** Check flagged words inline or click **Run Spell Check (US)**.
6. **Transmit:** Click **TRANSMIT DISPATCH**.

### 2. Manage Roster
- **Search:** Instant filter search box by callsign, name, tag, or email address.
- **Add / Edit:** Fill operator details on the right panel and click **Save / Update**.
- **CSV Import:** Click **Import Google CSV** to import a contact list exported from Google Contacts.

### 3. Queue Manager
- View all pending scheduled transmissions.
- Cancel scheduled dispatches before their timer expires.

---

## 🔍 US Spell Check System

The alert system integrates `pyspellchecker` configured for American English:
- **Debounced Live Inspection:** Highlights unrecognized words with a red underline as you type.
- **Context Menu Integration:** Right-click directly on any underlined word to view quick correction suggestions and replace it with one click.
- **Domain Lexicon:** Custom radio operator terms (`callsign`, `simplex`, `repeater`, `ARES`, `RACES`, etc.) are recognized by default and won't trigger false positives.

---

## 📥 Google Contacts CSV Import

The built-in parser automatically normalizes Google Contacts fields:
- **Callsign Extraction:** Recognizes callsigns stored in brackets (e.g. `John Doe [K1ABC]`) or in the Notes field.
- **Group Mapping:** Extracts tags (`ARES`, `RACES`, `SKYWARN`, `LEADER`, `EC`) from Group Membership and Notes columns.
- **SMS Gateway Synthesis:** Converts clean 10-digit phone numbers into SMS email gateways (defaults to `@vtext.com`).

---

## 🗄 Database Structure

The local database is saved automatically as `contacts_db.json`:

```json
{
  "smtp_settings": {
    "server": "smtp.gmail.com",
    "port": 587,
    "email": "dispatch@example.com",
    "password": "app-password-here"
  },
  "contacts": [
    {
      "callsign": "W1AW",
      "name": "Hiram Percy Maxim",
      "email": "w1aw@example.org",
      "phone_gateway": "2035550199@vtext.com",
      "tags": "ARES, LEADER",
      "receive_email": true,
      "receive_text": true
    }
  ]
}
```

---

## 📄 License

Distributed under the **MIT License**. See `LICENSE` for details.