gridpilot.gg/docs/MESSAGING.md

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.