v2 Gap Analysis — Communication

Communication — V2 Review Gap Analysis

Source: BACKEND-RAMBLINGS.md lines 271–286

Spec: Communication is not a dedicated spec doc; scattered across:

• 04-semester-management.md Section 5 (Email Management — automated templates only)
• 10-admin-system.md Section 4 (Notifications — broadcast push only)

Implementation: Two screens exist:

• /src/pages/semester-management/email-management.tsx
• /src/pages/admin-system/notifications.tsx

Current state summary

Communication infrastructure in the spec is minimal and fragmented. Email Management exists only to configure event-triggered email templates (on registration, week start, semester end, etc.) for a semester; it does NOT cover blast emails, scheduled sends, or custom recipient lists. Notifications is a single broadcast screen with no recipient filtering. No logs, announcement board, private messaging, or sequence preview. This section is net-new as a dedicated domain — stakeholder's six subsections are almost entirely absent from current spec and implementation.

Screens covered (proposed)

• Automation Emails
• Blast Emails
• Push Notifications
• Announcement Board
• Private Messages
• Communication Logs

Automation Emails

Existing spec/impl coverage

Spec (04-semester-management.md Section 5):

• Screen: "Email Management"
• Scope: Create/edit/delete email templates; set trigger (On Registration, Week Start, Semester End, On Promotion, On Failure, Custom Date); configure subject, body, template variables ({{student_name}}, {{semester_name}}, {{level}}, {{ta_name}}); toggle Active/Draft status; test-send to admin email; clone from previous semester.
• Gap: No sequence preview. No ability to search a student and view their future email schedule. No configuration of multiple emails in sequence.

Impl (email-management.tsx):

• Basic template CRUD with modal editor, status badge, preview modal, test-send button.
• Gap: Same — no sequence/schedule view for a specific student.

Stakeholder asks

1. Set up automation emails triggered by events/dates
2. Write formatted drafts with template variable references (semester start, end, etc.)
3. Assign automations to a specific semester
4. Sequence view: Search for a student by name, see all emails they will receive in the future with exact delivery dates
5. View dates and exact emails for an example student

Ambiguous

• Does sequence view populate sample data or actual enrolled students? (Spec assumes sample student)
• What counts as an "event"? Just the 6 triggers above, or custom webhooks?
• Can automations reference custom fields (e.g., TA name, student's level at send time)?
• How many emails typically in a sequence per semester? (Impacts UI layout — timeline, list, or cards)

Blast Emails

Existing spec/impl coverage

Spec: None. Not mentioned in 04-semester-management.md or elsewhere.

Impl: None.

Stakeholder asks

1. Compose an email or choose from a template library
2. Select recipients by:
   • Level (from level_tag table)
   • Course (mastery course)
   • Gender (from user profile)
   • Custom list (copy/paste from student reports)
3. Create and save email templates for reuse
4. Send immediately to selected list

Ambiguous

• Template storage: Separate from automation email templates, or shared library?
• Scheduling: Send now only, or schedule for future date/time?
• Recipient preview: Show recipient count and sample names before send?
• Send confirmation: Require admin confirmation, or send on form submission?
• Tracking: Should blast emails be logged in Communication Logs with delivery status?

Push Notifications

Existing spec/impl coverage

Spec (10-admin-system.md Section 4):

• Screen: "Notifications" under Admin & System
• Scope: "Send broadcast push notifications" to all users; relocated from Settings.
• No recipient filtering documented.

Impl (notifications.tsx):

• Basic form to send a notification to all users.
• Gap: No recipient filtering (level, course, gender, custom list).

Stakeholder asks

1. Draft a push notification message
2. Select recipients by:
   • Level
   • Course/mastery course
   • Gender
   • Specific students only
   • Custom list
3. Purpose: Inform students of urgent/time-sensitive program changes
4. Send to selected students

Ambiguous

• Can TAs or support staff send push notifications, or admin-only?
• Rich text / formatting in push message, or plain text only?
• Can notifications reference template variables (e.g., student name)?
• Delivery confirmation: Show success/failure per student, or aggregate count only?
• Scheduling: Send now only, or schedule for later?

Announcement Board

Existing spec/impl coverage

Spec: None.

Impl: None.

Stakeholder asks

1. Draft a message for the announcement board (visible in student and/or teacher app)
2. Post to announcement board with recipient targeting:
   • All students
   • All teachers
   • By level
   • By mastery (course)
   • By course
   • By gender
3. Purpose: Inform students/teachers of program updates, fixes, surveys, etc. (less urgent than push notifications)

Ambiguous

• Does message appear immediately, or can it be scheduled/drafted?
• Can announcements be edited or deleted after posting?
• Can TAs post announcements, or admin only?
• Can messages include rich text (images, links, formatting)?
• Does the announcement board have categories/tags for filtering?
• History/archival: How long do old announcements remain visible?

Private Messages

Existing spec/impl coverage

Spec: Partially in 10-admin-system.md Section 6 (Issue Queue):

• One-way student-to-admin channel for reporting issues. Not bidirectional messaging.
• No admin-to-student private messaging spec.

Impl: Issue Queue exists (issue-queue.tsx) but is ticket/issue tracking, not messaging.

Stakeholder asks

1. Admins send and receive private messages to/from students in a QF inbox
2. Two-way conversation (admin initiates or replies)

Ambiguous

• Is this in-app messaging only, or email-based?
• Do messages appear as a new app notification, or just in a messages inbox?
• Can multiple admins collaborate on a single message thread (e.g., thread shows all replies)?
• Reply notification: Does the student get a push notification or email when admin replies?
• Can attachments be sent (documents, PDFs)?
• Archive/delete permissions: Can admins delete old messages from threads?
• TA involvement: Can TAs message students, or admin-only?

Communication Logs

Existing spec/impl coverage

Spec: None.

Impl: None.

Stakeholder asks

1. View every message sent to students/teachers from the backend
2. Filter by:
   • Message type (email, push notification, announcement)
   • Student/teacher name or email (search)
   • Date range
   • Message title or content (search)
3. Flag messages that failed to deliver
4. Show delivery status for each message

Ambiguous

• What counts as "sent"? Queued, delivered to device, read, or clicked?
• Does log include private messages (admin-to-student) or only one-way broadcasts?
• Retry mechanism: If a message failed, can admin retry from the log screen?
• Audit trail: Should log show which admin/TA sent the message, or just the backend?
• Export: Can logs be exported to CSV for reporting?
• Retention: How long are logs kept (all history or recent only)?
• Delivery status granularity: Per-user status (e.g., "sent to 450 students, 12 failed") or detailed per-recipient?

Cross-cutting: Identity switching (send as TA or admin)

Stakeholder's ask (line 286):

"Any of the communication from the backend to the student can be done in the name of one of the TAs as well, or under the name of one of the admins."

Implications

1. Identity selector: Every communication screen (blast email, push, announcement, private message) needs a "Send as" dropdown to pick the signing admin/TA.
2. Display name: Student receives email/message/announcement with TA or admin name in sender field, not generic "QuranFlow Admin."
3. Audit trail: Log must record which admin/TA composed AND which admin/TA is named as sender (may differ).
4. TA awareness: Should the selected TA be notified that a message was sent in their name? Or is this silent?
5. Reply handling: If student replies to an email sent "as TA Ahmed," does reply go to Ahmed's inbox, the original composer, or both?
6. Permissions: Can all admins send as any TA? Or restricted by TA assignment / team?

Ambiguous

• Is this feature for all communication types or just email/private messages?
• Should the TA/admin being sent-as receive a copy of the message for their records?
• If a TA is later deactivated, can old messages still show their name, or should sender be redacted?

Summary

• Domain scope: Communication is a new top-level navigation section (not yet in spec index or sidebar). Structural impact: adds 1 new domain to sidebar, creates 6 new screens (Automation Emails, Blast Emails, Push Notifications, Announcement Board, Private Messages, Communication Logs).

• Estimated screen counts:

  • Automation Emails: ~1 screen (existing Email Management + new Sequence View tab or modal)
  • Blast Emails: 1 screen
  • Push Notifications: 1 screen (enhance existing Notifications with recipient filtering)
  • Announcement Board: 1 screen
  • Private Messages: 1 screen (separate from existing Issue Queue)
  • Communication Logs: 1 screen
  • Total: 6 screens (1 new UI addition to existing Email Management, 5 fully new)

• Top ambiguities:

  1. Sequence view data source: Does it show all students, or sample, or only a specific student search? Impacts query scope.
  2. Template libraries: Are blast email templates separate from automation templates, or unified? Affects data model.
  3. Scheduling: Do any communication types support future scheduling, or send-now only? Affects form complexity.
  4. Identity switching scope: Which screens require "Send as"? All, or only email/messages? Affects UI consistency.
  5. Private messages bidirectionality: Is this in-app only, or can students reply via email? Affects notification/delivery design.
  6. Announcement board permissions: Admin-only, or can TAs post? Affects role-based access.

• Spec dependencies:

  • Email Management spec is partial (templates only); needs expansion to cover Automation Emails full scope + Sequence View.
  • Notifications spec assumes broadcast-only; needs enhancement for recipient filtering and redesign for new Push Notifications screen.
  • No spec precedent for Blast Emails, Announcement Board, Private Messages, Communication Logs, or identity switching.

• Implementation readiness:

  • Email Management and Notifications screens partially exist but incomplete. 5 screens require full build.
  • Identity switching affects all 6 screens with a consistent "Send as" pattern.