auth

docs/MESSAGING.md

@@ -0,0 +1,247 @@
+# 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.