v2 Admin Spec — Communication (New 9th Domain)

Communication

Domain 9 of the v2 navigation structure (NEW domain — IA shifts from 8+1 to 9+1 domains). Contains: Automation Emails (absorbed, enhanced), Blast Emails (NEW), Push Notifications (absorbed, enhanced), Announcement Board (NEW), Private Messages (NEW), Communication Logs (NEW). This domain is entirely new. It consolidates outbound communication previously scattered across Semester Management (Email Management) and Admin & System (Notifications), and introduces four net-new channels. Primary workflows served: WF1 (Semester Setup — welcome and onboarding emails), WF2 (Student Support — 1:1 messaging, pre-drafted TA communication), WF4 (Daily Monitoring — announcement board, urgent push notifications)

1. Domain Overview

Communication is a new top-level domain introduced in v2 (ADR-003). It unifies all outbound communication — automated emails, blast email campaigns, push notifications, announcements, and 1:1 messaging — into a single sidebar section with a consistent compose/preview/send pattern, shared recipient filtering, and a unified delivery log.

Two categories of communication live here:

• Broadcast (many recipients, one-way): Automation Emails, Blast Emails, Push Notifications, Announcement Board
• Conversational (two-way): Private Messages (bidirectional student↔teacher inbox)

The Communication Logs screen provides a unified audit trail across all six channels.

1.1 Domain Boundary: Issue Queue Stays in Admin & System

ADR-003 explicitly preserves Issue Queue (10-admin-system.md §6) in Admin & System. Issue Queue is ticketed support — students report app problems, admins triage and resolve them with a state machine (Under Review / In Progress / Resolved). It is not messaging: there is no freeform thread, no inbox paradigm, no TA routing.

Private Messages (this domain §6) is the messaging channel. If a student opens an issue ticket and then needs a conversational follow-up, the admin can initiate a Private Message from the issue detail view (Admin & System > Issue Queue > Issue Detail > "Start Message" action, deep-linking to Communication > Private Messages with prefilled recipient).

1.2 Identity Model: No Impersonation, Pre-draft Instead (ADR-004)

Admins cannot send communications "as" a TA. The original "Send as TA" proposal was rejected because it would have required dual-identity records (composed_by, sent_as), reply-routing logic, and TA-awareness notifications across every communication screen.

Instead, the domain uses a pre-draft pattern:

1. Admin composes a message and selects "Draft for TA" → picks a TA from dropdown → saves draft.
2. The draft is assigned to that TA's outbox.
3. The TA reviews the draft in their own account (TA-facing queue is production-only; the mockup shows the admin's "Draft for TA" action but not the TA queue).
4. The TA edits if desired and hits Send. The message genuinely comes from the TA: authentic sender, correct reply-to, no audit ambiguity.

Communication Logs records a single sender identity per message (the TA who actually sent it, or the admin who sent it directly). There is no composed_by / sent_as split.

Screens supporting the pre-draft pattern (per ADR-004): Private Messages, Blast Emails. Push Notifications and Announcement Board are broadcast channels that don't benefit from personal-sender framing — they always go out under the "QuranFlow" system identity or the posting admin's name.

TA permissions on Announcement Board (per STAKEHOLDER-ANSWERS 2026-04-21, default #6 CHANGED): TAs can post and manage their own announcements on the Announcement Board (edit/delete their own posts, set audience, set expiry). Moderation of other authors' posts remains admin-only. See §5 for full role visibility.

1.3 Workarounds Eliminated

1.4 Data Architecture

Existing tables (preserved from v1):

• emails: id, name, subject, body, trigger_type, trigger_config, semester_id, status, template_variables, created_at, updated_at
• push_notifications: id, message, sent_by, sent_at, recipient_count (v1 table — enhanced in v2, see below)

New tables (v2 additions — to be validated during implementation):

• blast_emails: id, name, subject, body, template_id, recipient_filter_json, recipient_manual_ids, scheduled_for, sent_at, sender_user_id, predraft_for_ta_id, status (Draft / Scheduled / Sent / Failed), created_by, created_at
• email_templates: id, name, subject, body, template_variables, source_domain (automation / blast / unified) — unified library confirmed per STAKEHOLDER-ANSWERS (2026-04-21, OQ-C2 resolved); templates tagged by source_domain are reusable across Automation + Blast contexts. created_by, created_at, updated_at
• push_notifications (enhanced): add recipient_filter_json, recipient_count, delivered_count, failed_count, predraft_for_ta_id
• announcements: id, title, body, audience_filter_json, posted_by, posted_at, expires_at, status (Draft / Published / Expired / Deleted), read_receipt_enabled
• announcement_reads: id, announcement_id, user_id, read_at (populated if read_receipt_enabled)
• private_messages: id, thread_id, sender_user_id, recipient_user_id, body, attachments_json, sent_at, read_at, predraft_for_ta_id
• private_message_threads: id, subject, student_user_id, teacher_user_id, last_message_at, status (Open / Archived / Closed), created_by
• communication_logs: id, channel, source_record_id, sender_user_id, recipient_user_ids_json, subject_or_preview, status (Queued / Sent / Delivered / Failed / Read), predrafted (bool), predraft_ta_user_id (nullable), sent_at, delivered_at, failure_reason, created_at

1.5 Shared Recipient Filter (used by Sections 3, 4, 5)

Blast Emails, Push Notifications, and Announcement Board use the same recipient filter pattern. This is specified once here and referenced from each screen.

Filter dimensions (all AND-combined):

Manual selection (alternative to filters, per stakeholder Apr 15 decision — transcript lines 274–283):

• "Select Students Manually" toggle flips the recipient selection panel into a student-search multi-select (autocomplete by name/email, add to list, remove from list). The manual list can also be pasted as comma- or newline-separated emails/names (matched to users records).
• Filters and manual selection are mutually exclusive: switching modes clears the other mode's selection.

Preview bar (below filter or manual list):

• Live count: "[N] recipients selected"
• Sample names: "Sarah Ahmed, Ahmed Ali, Fatima Zahra, + [N-3] more"
• Gender/level breakdown (expandable): "Male: [X], Female: [Y] · Level 1: [A], Level 2: [B]..."

1.6 Cross-Cutting Conventions

• Status badges: all screens use the badges defined in 01-global-patterns.md §4.3, with additions: Draft (blue), Scheduled (amber), Sent (green), Delivered (green), Failed (red), Read (green), Unread (gray).
• Compose modals: follow the Modals pattern (01-global-patterns.md §4.10), max-width 800px for compose screens with preview.
• Template variables: {{student_name}}, {{semester_name}}, {{level}}, {{ta_name}}, {{teacher_name}}, {{appointment_date}}. Rendered with sample values in Preview modals.
• Role visibility defaults: Admin = full; View-Only = view logs/history, no send; TA = pre-draft queue and own sent items (production-only); Support Staff = view logs, no send.

2. Screen: Automation Emails

2.1 Purpose

Configure automated email templates that fire on student-lifecycle triggers (registration, week start, semester end, promotion, failure, custom date). Absorbed from v1 Semester Management > Email Management and enhanced with a Sequence View that lets an admin search a student and see every email that student will receive in the future, in order.

The semester-scoped template model is preserved exactly — each template belongs to one semester. The semester selector (previously the page's primary layout element) becomes a filter.

Transition hint: "Formerly under Semester Management > Email Management" — shown for first 30 days.

2.2 Entry Points

• Sidebar: Communication > Automation Emails
• Semester Hub > Setup Checklist: "Configure Email Templates →" deep link (preserved from v1; now cross-domain — opens Automation Emails filtered to that semester)
• Semester Hub > Overview: "View All Emails" link in Automation section
• Dashboard: n/a (no direct tile)

2.3 Layout

Two views, toggled at top of screen: Templates (default) | Sequence View.

Templates view: Filter bar + data table (standard Data Table pattern, 01-global-patterns.md §4.1).

Sequence View: Student search box at top + vertical timeline of upcoming emails for the selected student.

2.4 Templates View

2.4.1 Filter Bar

2.4.2 Data Displayed

2.4.3 Actions

2.4.4 Templates View States

2.4.5 System-Seeded End-of-Semester Templates (NEW)

Three system-seeded templates support End Checklist Step 3 (Send Pass/Fail Emails). These templates are system-integral (not deletable; content editable):

Note: These three templates are system-seeded and cannot be deleted, but their subject lines, bodies, and template variables are admin-editable. Trigger conditions are fixed (driven by End Checklist Step 3). System-seeded templates show a lock icon next to the name in the Templates view and their Delete action is hidden/disabled with tooltip "System template — can be edited but not deleted".

Mockup scope: static mock templates with placeholder bodies; triggering is mock-only.

2.5 Sequence View (NEW)

2.5.1 Purpose

Answer the question: "What emails will this student receive in the future, and when?" Stakeholder ask: "Search a student, see every email they will receive with exact delivery dates."

2.5.2 Layout

Student search at top (autocomplete, as per Global Search §2.2, scoped to students only) → on selection, renders a vertical timeline below.

2.5.3 Timeline Content

Each upcoming email the selected student will receive, based on:

• Their current enrollment (user_link_level_tag)
• The current semester's Active templates
• Evaluated trigger conditions (e.g., "Week 3 start" → if today is Mar 1 and Week 3 starts Mar 15, this email is 14 days out)

Open question (OQ-C1): whether Sequence View shows only the selected student's upcoming emails (current assumption) or a sample student as a preview when no student is searched. Per ADR-003, mockup defaults to searched student.

2.5.4 Sequence View Actions

2.5.5 Sequence View States

2.6 End Checklist Email Queue (NEW)

2.6.1 Purpose

Per-student queue of End Checklist Step 3 emails that have not yet been sent (or that failed/bounced). Shows each enrolled student's current final_status, the email template that applies to their track (pass / fail-opt-in / mastery-elective), the send status (Unsent / Queued / Sent / Failed / Bounced), and a per-student "Send Now" button to manually trigger the correct template. Provides admin a clear view of who is and isn't emailed during semester close, and a manual fallback for any student the automatic trigger missed.

2.6.2 Scope

All enrolled students in the closing semester. Branched by track:

• L1–L4 pass (final_status = 'pass' AND level IN (1,2,3,4)) → uses "End of Semester — Pass (L1–L4)" template.
• L1–L4 fail (final_status = 'fail' AND level IN (1,2,3,4)) → uses "End of Semester — Fail (L1–L4, Opt-in Repeat)" template.
• Mastery (level_tag.is_mastery = 1) → uses "End of Semester — Mastery Elective Prompt" template.
• Students in L1–L4 with final_status IS NULL appear in the queue with status "Awaiting Pass/Fail decision" (Set Pass/Fail deep-link → 03-student §2); they cannot be emailed until Step 2 sets their status.

Leavers are excluded (per STAKEHOLDER-ANSWERS-2026-04-21: "they handle their own enrollment and payment").

2.6.3 Entry Points

• Semester Hub > End Checklist > Step 3 ("Send Pass/Fail Emails"): deep link with URL ?from=end-checklist&semester=[id]&filter=unsent. When ?from=end-checklist is present, the screen shows a persistent "← Return to End Checklist for [Semester Name]" banner; clicking returns to the End Checklist tab with scroll position preserved.
• Sidebar: Communication > Automation Emails > "End Checklist Queue" tab (visible only when the semester filter is on a semester in Close phase).

2.6.4 Data Displayed

2.6.5 Filter Bar

2.6.6 Actions

2.6.7 States

2.6.8 Role Visibility

• Admin: Full queue + per-student Send Now + bulk send + View Log + Set Pass/Fail deep-link.
• View-Only: Queue view + View Log + Last Attempt timestamps. No send actions.
• TA: Hidden from sidebar tab; accessible only via the Set Pass/Fail deep-link return flow when completing own students' status. TA cannot trigger end-of-semester email sends — the automated system sends; admin does manual fallback.
• Support Staff: Queue view + View Log. No send actions.

2.7 Role Visibility

• Admin: Full CRUD on templates + Sequence View + all actions (Create, Edit, Delete, Preview, Test Send, Clone, Draft for TA, Send Now, Skip)
• View-Only: View templates list + Preview + Sequence View (read-only). No Create, Edit, Delete, Test Send, Clone, Draft for TA, Send Now, Skip.
• TA: Hidden (sidebar item not visible). TA sees pre-drafted items in their own outbox (production-only).
• Support Staff: View templates list + Preview + Sequence View (useful for answering "why did this student get this email?"). No send or edit actions.

3. Screen: Blast Emails (NEW)

3.1 Purpose

Compose and send one-off emails to a filtered or manually selected list of students/teachers. Unlike Automation Emails (event-triggered, per-student), Blast Emails are admin-initiated, multi-recipient, one-time sends. Supports pre-drafting for TAs (ADR-004).

3.2 Entry Points

• Sidebar: Communication > Blast Emails
• Dashboard: "Send Blast Email" quick action (Admin only)
• Student Management > Students list: "Email Selected" bulk action (with recipients pre-populated from selection)

3.3 Layout

Two views: Campaigns (list of past/scheduled/draft blasts, default) | Compose (full-screen compose).

3.4 Campaigns View

3.4.1 Filter Bar

Note on "Scheduled" records: Scheduling is production-only per STAKEHOLDER-ANSWERS-2026-04-21 (default #5). The Schedule button is removed from the Compose view (§3.5.3), so the mockup cannot create Scheduled campaigns. The Status filter, Scheduled For column, and Cancel Scheduled action are retained for forward-compatibility with production (where Scheduled records will exist) but mockup fixtures will contain no Scheduled rows.

3.4.2 Data Displayed

3.4.3 Campaign Actions

3.4.4 Campaigns View States

3.5 Compose View

Three-section layout: Recipients (top) → Message (middle) → Review & Send (bottom, sticky).

3.5.1 Recipients Section

Uses the Shared Recipient Filter defined in Section 1.5. Mode toggle: "Filter by Criteria" (default) | "Select Manually".

Live preview bar at bottom of section: "[N] recipients selected. Sarah Ahmed, Ahmed Ali, +12 more."

Save as Audience (optional): "Save this selection as a named audience" — persists the filter JSON for reuse across blasts. Named audiences appear in a dropdown above the filter: "Use Saved Audience →". Open question (OQ-C4): are saved audiences shared across admins or private per admin.

3.5.2 Message Section

3.5.3 Review & Send Section (sticky footer)

Scheduled sends deferred to production per STAKEHOLDER-ANSWERS 2026-04-21 (default #5). v2 mockup supports Send Now and Save Draft only; scheduled publishing will be added in production. The blast_emails.scheduled_for column is preserved in the data model for production use; only the UI Schedule button is removed from the mockup.

3.5.4 Compose View Actions (full table)

3.6 Role Visibility

• Admin: Full compose, send, pre-draft, and campaign management. Scheduling is production-only (see §3.4.1 note).
• View-Only: View Campaigns list + View individual campaigns (read-only). Cannot Compose, Send, Duplicate, Delete, or Draft for TA.
• TA: Hidden (sidebar item not visible). TA sees their pre-drafted blasts in a production-only outbox.
• Support Staff: View Campaigns list + View individual campaigns. No send actions.

4. Screen: Push Notifications

4.1 Purpose

Send push notifications to the mobile app. Absorbed from v1 Admin & System > Notifications and enhanced with the shared recipient filter (Section 1.5), delivery tracking (sent/delivered/failed counts), and a history view. Push notifications are reserved for urgent/time-sensitive communications (urgent session changes, emergency program updates).

Transition hint: "Formerly under Admin & System > Notifications" — shown for first 30 days.

4.2 Entry Points

• Sidebar: Communication > Push Notifications
• Dashboard: "Send Notification" quick action (retargeted from v1 Admin & System > Notifications per ADR-003)

4.3 Layout

Two-pane: Compose (top, sticky form) | History (below, data table of past notifications).

4.4 Compose Pane

4.4.1 Fields

4.4.2 Actions

Scheduled sends deferred to production per STAKEHOLDER-ANSWERS 2026-04-21 (default #5). v2 mockup supports Send Now only; scheduled publishing will be added in production. The push_notifications.scheduled_for column is preserved in the data model for production use; only the UI Schedule button is removed from the mockup.

4.5 History Pane

4.5.1 Filter Bar

Note on "Scheduled" records: Scheduling is production-only per STAKEHOLDER-ANSWERS-2026-04-21 (default #5). The Schedule button is removed from the Compose view (§4.4.2), so the mockup cannot create Scheduled push notifications. The Status filter and Cancel Scheduled action are retained for forward-compatibility with production.

4.5.2 Data Displayed

4.5.3 History Actions

4.6 States

4.7 Role Visibility

• Admin: Full compose + send + history view. Scheduling is production-only (see §4.5.1 note).
• View-Only: View History only. No Compose pane shown (or shown disabled).
• TA: Hidden (sidebar item not visible)
• Support Staff: View History only. No Compose pane.

5. Screen: Announcement Board (NEW)

5.1 Purpose

Post in-app announcements to students and/or teachers. Replaces the community board concept with a one-way, authored channel. Used for non-urgent program updates, surveys, fix notes, policy changes — things that don't warrant a push notification but should be visible to users when they open the app.

Admins and TAs can post to the Announcement Board (per STAKEHOLDER-ANSWERS 2026-04-21, default #6 CHANGED). TAs can manage their own posts (edit/delete/set audience/set expiry). Moderation of others' posts is admin-only.

Students see the announcement in a dedicated in-app announcement area. Teachers (TAs) see posts targeted to them similarly.

5.2 Entry Points

• Sidebar: Communication > Announcement Board
• Dashboard: "Post Announcement" quick action

5.3 Layout

Two-pane: Active Announcements (top, card list of currently visible posts) | All Posts (below, full history table with filter bar).

5.4 Active Announcements Pane

A card list of announcements where status = Published AND expires_at is in the future (or null).

Each card shows:

• Title (bold)
• Body preview (first 200 chars)
• Audience summary (e.g., "All students" or "Level 2 + Level 3 students")
• Posted date + author
• Expiry countdown ("Expires in 5 days" / "No expiry")
• Actions: Edit / Delete / Expire Now / View Read Receipts (if enabled)

5.5 All Posts Pane

5.5.1 Filter Bar

5.5.2 Data Displayed

5.6 Post Announcement Compose Modal

5.7 Actions

5.8 States

5.9 Role Visibility

• Admin: Full posting, full moderation. CRUD on any post (Post, Edit, Delete, Expire, View Read Receipts). Sidebar: visible.
• View-Only: View Active Announcements + All Posts table (read-only). No Post, Edit, Delete, Expire actions. View Read Receipts accessible.
• TA: Can post and manage their own posts (edit/delete/expire/set audience/set expiry their own). Cannot moderate or edit others' posts. Cannot view draft posts from other authors. Can read all published posts. Sidebar: visible. (Per STAKEHOLDER-ANSWERS 2026-04-21, default #6 CHANGED.)
• Support Staff: View Active + All Posts (read-only). Useful context for student inquiries ("what was just announced?").

6. Screen: Private Messages (NEW)

6.1 Purpose

Bidirectional conversational messaging between admins, teachers (TAs), and students. Replaces ad-hoc WhatsApp/email for student support and teacher-student check-ins. This is the core screen for the pre-draft pattern (ADR-004): an admin can compose a message, assign it as a draft to a TA, and the TA sends it from their own account.

Key design points (per ADR-003, ADR-004):

• Bidirectional — students can initiate, teachers can initiate, admins can initiate.
• No impersonation — every message has a single sender identity.
• Admins can view all conversations (moderation/support) but cannot impersonate participants.
• Admin pre-draft flow: admin composes a message targeted to a specific student, selects a TA, saves as draft. The TA's account picks it up and they send.

6.2 Entry Points

• Sidebar: Communication > Private Messages
• Student Detail > Profile tab: "Message" action (initiates a new thread or opens existing)
• Teacher Detail > Profile tab: "Pre-draft for [TA]" action (opens compose with TA locked as sender)
• Admin & System > Issue Queue > Issue Detail: "Start Message" action (initiates thread with issue reporter)

6.3 Layout

Three-pane inbox layout:

• Left: Conversation list (threads)
• Middle: Selected thread — message list (scrollable, newest at bottom) + reply composer at bottom
• Right (contextual, admin only): Participant context panel (student/TA profile summary, recent submissions, recent payments — helpful for support conversations)

6.4 Conversation List (left pane)

6.4.1 Filter Bar

6.4.2 Thread Card Fields

6.5 Thread View (middle pane)

6.5.1 Header

6.5.2 Message List

Each message rendered as a bubble aligned by sender (viewer's messages right, others left).

6.5.3 Reply Composer (sticky bottom)

6.6 Admin Context Panel (right pane, admin view only)

When an admin is viewing a thread, a right-side panel shows context about the student participant:

This panel is view-only and does not appear for the TA view (TAs already have student context in their own UI).

6.7 Compose New Thread

Triggered from "New Message" button in conversation list, or from cross-domain entry points (Student Detail, Teacher Detail).

Actions: Send (immediate, creates thread + first message) / Save Draft (draft thread, not visible to recipient) / Draft for TA (saves as pre-draft; TA sends first message from their own account).

6.8 Actions (thread-level)

6.9 States

6.10 Role Visibility

• Admin: View all threads across all students/TAs; send as self; pre-draft for TAs; archive, close, reopen, delete threads/messages; export
• View-Only: View all threads (read-only). No send, no draft, no archive/close/delete. Useful for supervisors/auditors.
• TA: View only threads they participate in (own conversations with their students) + pre-drafts targeted to them (production-only queue). Send and reply in own threads. Cannot see other TAs' threads.
• Support Staff: View all threads (read-only) to support student inquiries. No send, no draft, no moderation actions.
• Students: Not a backend role — but their app-side experience pairs with this screen: they see threads initiated by admin or their TA, can reply, cannot initiate new threads against arbitrary admins (routing rules TBD, OQ-C9).

7. Screen: Communication Logs (NEW)

7.1 Purpose

Unified audit trail of every message sent from the backend, across all five outbound channels (automation email, blast email, push notification, announcement, private message). Supports filtering, full-message viewing, delivery-status investigation, and CSV export.

Distinct from Reporting > Logs (09-reporting.md §6), which covers system events (logins, record changes, admin actions). Communication Logs is communication-specific.

7.2 Entry Points

• Sidebar: Communication > Communication Logs
• Automation Emails > Template row > "View Send History" link
• Blast Emails > Campaign detail > "View Delivery" link
• Push Notifications > History row > "View Details" link
• Private Messages > Thread > "View in Logs" action (admin only)
• Student Detail > [future tab] > "Communication History" (cross-domain integration)

7.3 Layout

Standard filter bar + data table + pagination, following 01-global-patterns.md §4.1 and §4.2.

7.4 Filter Bar

7.5 Data Displayed

7.6 Actions

7.7 Pagination

Standard pagination (01-global-patterns.md §4.1): 50 records per page (higher than default 25 because logs are expected to be high-volume), "1–50 of 3,472" format.

7.8 States

7.9 Role Visibility

• Admin: Full view + all actions (View, Retry, Open Source, Export)
• View-Only: Full view + View Full Message + Open Source. No Retry, no Export.
• TA: View only their own sent messages (pre-drafted or self-sent). No Retry, no Export. Sidebar visibility open question (OQ-C10) — mockup hides from TA sidebar.
• Support Staff: Full view + View Full Message + Open Source + Export (Export is critical for support ticket evidence). No Retry.

8. Cross-Domain Integration Points

This section documents how Communication connects to other domains. Each integration is specified in detail in the target domain's spec document; this section provides a summary for reference.

8.1 Semester Management (04-semester-management.md)

8.2 Student Management (03-student-management.md)

8.3 Teacher Management (07-teacher-management.md)

8.4 Billing & Payments (08-billing-payments.md)

8.5 Admin & System (10-admin-system.md)

8.6 Dashboard (02-dashboard.md)

8.7 Reporting (09-reporting.md)

9. Assumptions and Open Questions

This domain is net-new and introduces several decisions that require stakeholder validation. Summary of communication-specific open questions, consolidated from ADR-003, ADR-004, and Framework v2 §3.6:

Preserved assumptions from absorbed domains:

• emails table semester-scoping is preserved exactly — no data migration required from v1 Email Management.
• push_notifications table schema is extended (not replaced) — v1 records remain valid; new fields (recipient_filter_json, delivered/failed counts, predraft_for_ta_id) default to null for legacy rows.