Communications Experience Layer Guide

Purpose

Task 85 turns communications into a planner-facing and participant-aware product surface on top of the shared communications domain. The experience layer keeps message composition, delivery, reminders, history, and participant entry points inside Tov+ instead of scattering them across modules.

Planner workflow

Planners use the communications workspace to:

• save or revise occasion-scoped drafts
• choose a reusable template and channel
• target audiences by occasion, event, actor, RSVP state, and task state
• preview real personalization and deep links against a sample recipient
• send immediately or schedule later
• cancel scheduled draft-backed deliveries before they are processed
• review reminder suggestions and send history from one surface

The planner UI operates only through backend communications APIs. Product code does not talk directly to Novu.

Audience model

Audience selection is represented by CommunicationAudienceQueryRecord.

Supported filters:

• audience kind: guest, vendor, planner, admin, system
• scope: occasion, event, actor, group, household, vendor, task, module
• actor and user ids
• group and household membership expansion
• vendor actor targeting
• RSVP states
• task states
• module keys
• participation window
• free-text actor search

Audience resolution runs on the server against live actors, event participation, RSVP data, and unified tasks. Empty audiences are rejected during preview/send flows.

Templates and previews

Templates remain the system of record for message rendering. Occasion-specific templates can override or extend shared templates without bypassing the communications domain.

Preview rendering uses the same interpolation pipeline as sending and resolves:

• recipient display name
• event name
• occasion name
• guest access deep links
• vendor update links
• planner return links
• draft payload variables

Send and schedule model

Drafts carry the planner intent. Sends create thread, message, and delivery records through the communications domain.

Supported draft lifecycle:

• draft
• scheduled
• sent
• cancelled

Supported delivery lifecycle surfaced to product users:

• queued
• scheduled
• sent_to_provider
• delivered
• opened
• clicked
• retry_pending
• permanently_failed
• cancelled
• suppressed

Draft cancellation marks linked scheduled deliveries as cancelled before worker pickup when possible.

Reminder model

Reminder suggestions are generated from live occasion data and task state.

Current reminder shortcuts:

• RSVP pending reminders
• guest form completion reminders
• event update reminders
• vendor reminders
• campaign resend suggestions for failed campaign-backed sends

Reminder sends still flow through the same draft and delivery pipeline, so planner history remains complete.

Participant visibility

Guests see a recent message summary on the guest home surface when a delivery targeted their actor. The summary is intentionally lightweight and excludes planner-only metadata.

Vendors already consume scoped communications history through the vendor communications surface and continue to do so through the same shared communications records.

Permissions and safety

• planner communication history requires communications:view
• draft creation, sending, cancellation, and template editing require communications:manage
• recipient resolution respects authorization, notification preferences, locale resolution, and guest token safety
• message-linked actions use Tov+ deep links, not raw provider links

Integration points

The communications experience layer integrates with:

• unified tasks for reminder targeting
• distribution campaigns via shared delivery history
• automation-triggered sends through the same history model
• guest experience through recent message visibility
• vendor experience through scoped delivery history
• observability through delivery status aggregation