# GridPilot — Messaging & Communication System  
**Design Document (Code-First, Admin-Safe)**

---

## 1. Goals

The messaging system must:

- be **code-first**
- be **fully versioned**
- be **safe by default**
- prevent admins from breaking tone, structure, or legality
- support **transactional emails**, **announcements**, and **votes**
- give admins **visibility**, not creative control

This is **not** a marketing CMS.  
It is infrastructure.

---

## 2. Core Principles

### 2.1 Code is the Source of Truth
- All email templates live in the repository
- No WYSIWYG editors
- No runtime editing by admins
- Templates are reviewed like any other code

### 2.2 Admins Trigger, They Don’t Author
Admins can:
- preview
- test
- trigger
- audit

Admins cannot:
- edit wording
- change layout
- inject content

This guarantees:
- consistent voice
- legal safety
- no accidental damage

---

## 3. Template System

### 3.1 Template Structure

Each template defines:

- unique ID  
- version  
- subject  
- body (HTML + plain text)  
- allowed variables  
- default values  
- fallback behavior  

Example (conceptual):

- `league_invite_v1`
- `season_start_v2`
- `penalty_applied_v1`

Templates are immutable once deprecated.

---

### 3.2 Variables

- Strictly typed
- Explicit allow-list
- Required vs optional
- Default values for previews

Missing variables:
- never crash delivery
- always fall back safely

---

## 4. Admin Preview & Testing

### 4.1 Preview Mode

Admins can:
- open any template
- see rendered output
- switch between HTML / text
- inspect subject line

Preview uses:
- **test data only**
- never real user data by default

---

### 4.2 Test Send

Admins may:
- send a test email to themselves
- choose a predefined test dataset
- never inject arbitrary values

Purpose:
- sanity check
- formatting validation
- confidence before triggering

---

## 5. Delivery & Audit Trail

Every sent message is logged.

For each send event, store:
- template ID + version
- timestamp
- triggered by (admin/system)
- recipient(s)
- delivery status
- error details (if any)

Admins can view:
- delivery history
- failures
- resend eligibility

---

## 6. Trigger Types

### 6.1 Automatic Triggers
- season start
- race reminder
- protest resolved
- penalty applied
- standings updated

### 6.2 Manual Triggers
- league announcement
- sponsor message
- admin update
- vote launch

Manual triggers are:
- explicit
- logged
- rate-limited

---

## 7. Newsletter Handling

Newsletters follow the same system.

Characteristics:
- predefined formats
- fixed structure
- optional sections
- no free-text editing

Admins can:
- choose newsletter type
- select audience
- trigger send

Admins cannot:
- rewrite copy
- add arbitrary sections

---

## 8. Voting & Poll Messaging

Polls are also template-driven.

Flow:
1. Poll defined in code
2. Admin starts poll
3. System sends notification
4. Users vote
5. Results summarized automatically

Messaging remains:
- neutral
- consistent
- auditable

---

## 9. Admin UI Scope

Admin interface provides:

- template list
- preview button
- test send
- send history
- delivery status
- trigger actions

Admin UI explicitly excludes:
- template editing
- layout controls
- copywriting fields

---

## 10. Why This Matters

This approach ensures:

- trust
- predictability
- legal safety
- consistent brand voice
- low operational risk
- no CMS hell

GridPilot communicates like a tool, not a marketing department.

---

## 11. Non-Goals

This system will NOT:
- support custom admin HTML
- allow per-league copy editing
- replace marketing platforms
- become a newsletter builder

That is intentional.

---

## 12. Summary

**Code defines communication.  
Admins execute communication.  
Users receive communication they can trust.**

Simple. Stable. Scalable.