247 lines
3.7 KiB
Markdown
247 lines
3.7 KiB
Markdown
# 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. |