184 lines
7.1 KiB
Markdown
184 lines
7.1 KiB
Markdown
# 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., `[email protected]`).
|
|
- **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": "[email protected]",
|
|
"password": "app-password-here"
|
|
},
|
|
"contacts": [
|
|
{
|
|
"callsign": "W1AW",
|
|
"name": "Hiram Percy Maxim",
|
|
"email": "[email protected]",
|
|
"phone_gateway": "[email protected]",
|
|
"tags": "ARES, LEADER",
|
|
"receive_email": true,
|
|
"receive_text": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
Distributed under the **MIT License**. See `LICENSE` for details.
|