Files

T

2026-08-20 06:07:59 -04:00

7.1 KiB

Raw Permalink Blame History

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.

✨ 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 (US English dictionary checking & suggestions)

🚀 Installation & Quickstart

Clone the repository:

git clone https://github.com/your-org/ccar-alert-portal.git
cd ccar-alert-portal

Create a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate    # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install pyspellchecker
```
Launch the application:
```
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	`[email protected]`	`[email protected]`
App Password	SMTP account password or App Password	`xxxx xxxx xxxx xxxx`	`SecretPassword123`

Note for Gmail Users: Use an App Password rather than your personal Google account password if 2-Factor Authentication is enabled.

📖 Usage Guide

1. Send Dispatch

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.
Select Channels: Toggle Send via Email and/or Send via Text (SMS).
Set Transmission Timing:
- Select Send Immediately or Schedule Deployment (provide MM-DD-YY and 24-hour HH:MM).
Draft Alert Message: Type plain text or basic HTML tags (<b>, <i>, <br>).
Spell Check: Check flagged words inline or click Run Spell Check (US).
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:

{
  "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.

7.1 KiB Raw Permalink Blame History