Skip to content

Communication and Notifications

  • Q: When a new message thread is created and routed to a team (e.g., "admins"), who receives the notification? → A: All members who have that particular notification enabled either in-app or email
  • Q: When a user's WebSocket connection drops, what is the reconnection behavior? → A: delegated to frontend websockets provider

User Scenarios & Testing (mandatory)

User Story 1 - Sponsor Submits Event Query (Priority: P1)

A sponsor has a question about their stand configuration for an upcoming event and needs to contact the organiser. They create a new message thread which automatically routes to the event organiser, who receives both an email notification and an in-app alert. The organiser responds within the thread, and the sponsor is notified immediately through their chosen notification method.

Why this priority: This is the core messaging functionality that enables basic communication between sponsors and organisers. Without this, sponsors cannot get help with event-specific questions, which is essential for the platform's primary purpose.

Independent Test: Can be fully tested by having a sponsor create a message about an event, verifying it routes to the correct organiser, and confirming both parties receive notifications and can exchange responses.

Acceptance Scenarios:

  1. Given a sponsor is viewing their event dashboard, When they click "Contact Organiser" and submit a question about stand requirements, Then a message thread is created and routed to the event organiser
  2. Given a message thread has been created by a sponsor, When the organiser logs in, Then they see an unread message notification and can view the full thread
  3. Given an organiser has responded to a sponsor's message, When the response is submitted, Then the sponsor receives a notification through their preferred channel (email or in-app)
  4. Given a sponsor has in-app notifications enabled, When they are logged in and a new response arrives, Then they see a real-time notification without refreshing the page

User Story 2 - Sponsor Requests Artwork Assistance (Priority: P1)

A sponsor encounters a technical issue while uploading artwork and needs admin support. They create a message with the subject "Artwork Upload Problem" which automatically routes to the admin team. The admin team receives immediate notification and can respond with troubleshooting steps, with all communication tracked in a threaded conversation.

Why this priority: Artwork management is a critical workflow, and sponsors need quick access to technical support when issues arise. This is equally important to event queries as it unblocks sponsors from completing their required tasks.

Independent Test: Can be tested by having a sponsor create an artwork-related message, verifying it routes to admins (not organisers), and confirming the admin team can respond and resolve the issue within the thread.

Acceptance Scenarios:

  1. Given a sponsor is on the artwork management page, When they create a message with an artwork-related subject, Then the message is automatically routed to the admin team
  2. Given a message has been routed to admins, When an admin views their message inbox, Then they see the new thread marked as "Artwork Query"
  3. Given an admin responds to an artwork query, When the sponsor receives the response, Then they can continue the conversation in the same thread without creating a new message

User Story 3 - User Customises Notification Preferences (Priority: P2)

A sponsor who receives many notifications prefers to check the platform regularly rather than receive email alerts. They navigate to their profile settings and configure their notification preferences to receive in-app notifications only for new messages, while keeping email notifications enabled for payment confirmations and deadline reminders.

Why this priority: Notification fatigue is a real concern, and users need control over how they're contacted. This improves user experience but isn't required for basic communication functionality to work.

Independent Test: Can be tested by having a user update their notification preferences for different notification types, then triggering those notification types and verifying they are delivered only through the selected channels.

Acceptance Scenarios:

  1. Given a user is in their profile settings, When they view the notification preferences section, Then they see a list of all notification types with options to enable/disable email and in-app notifications for each
  2. Given a user has disabled email notifications for message responses, When they receive a new message response, Then they only receive an in-app notification and no email is sent
  3. Given a user has enabled both email and in-app notifications for a notification type, When that notification is triggered, Then they receive both an email and an in-app alert
  4. Given a user has disabled all in-app notifications, When notifications are triggered, Then they still receive emails (if email is enabled) and can view notifications in their notification history

User Story 4 - Admin Configures Message Types and Routing (Priority: P2)

An admin needs to adjust how messages are routed because the organisation has added a new team to handle sponsorship package queries. They access the system settings and create a new message type called "Sponsorship Enquiry" and configure it to route to the sales team rather than event organisers. When sponsors create messages, they select from available message types.

Why this priority: Flexible routing is important for scaling the platform as organisations grow and add new teams, but the system can function with basic message types initially. This can be implemented after core messaging works.

Independent Test: Can be tested by an admin creating or modifying message types and routing rules, then having sponsors create messages of different types and verifying they route to the correct recipients.

Acceptance Scenarios:

  1. Given an admin is in system settings, When they navigate to message type configuration, Then they see a list of existing message types with options to add, edit, or remove types
  2. Given an admin creates a new message type with a routing destination, When a sponsor creates a message and selects that type, Then the message is routed to the configured recipient team
  3. Given a sponsor is creating a new message, When they view the message type selector, Then they see all active message types to choose from (each thread can only have one type)
  4. Given an admin modifies a message type's routing destination, When new messages of that type are created, Then they route to the updated destination (existing threads remain with original routing)

User Story 5 - User Receives Real-Time In-App Notification (Priority: P3)

An organiser is working in the platform reviewing sponsor registrations when a new message arrives from a sponsor. Without refreshing the page, a notification badge appears on the messages icon in the navigation bar, and a toast notification briefly displays in the corner of the screen with a preview of the message.

Why this priority: Real-time notifications enhance user experience and improve response times, but users can still function effectively by refreshing the page or checking their email. This is a polish feature that can be implemented after core functionality is stable.

Independent Test: Can be tested by having a user logged in while another user sends them a message, verifying the notification appears instantly without page refresh, and confirming the notification UI elements work correctly.

Acceptance Scenarios:

  1. Given a user is logged in with in-app notifications enabled, When a new message or response is sent to them, Then they see a real-time notification within 2 seconds without page refresh
  2. Given a notification arrives while a user is on any page, When the notification displays, Then it includes a preview of the message and a link to view the full thread
  3. Given multiple notifications arrive in quick succession, When they are displayed, Then they stack or queue appropriately without overlapping or blocking the interface
  4. Given a user clicks on a notification toast, When they are navigated to the relevant content, Then the notification is marked as read

Edge Cases

  • What happens when a message doesn't match any routing rule? (Default behaviour needed)
  • How does the system handle messages sent to users who have deleted their accounts or been removed from events?
  • What happens if a user has disabled all notification methods for a critical notification type?
  • How are notifications handled for users who are logged in on multiple devices simultaneously?
  • What occurs when the real-time notification service is temporarily unavailable?
  • How does the system manage notification delivery for users in different time zones or with scheduled "do not disturb" preferences?
  • What happens to unread notifications when a user's role changes (e.g., organiser becomes admin)?
  • How are notification preferences migrated if notification types are added or removed in future updates?

Requirements (mandatory)

Functional Requirements

Message Management

  • FR-001: System MUST allow sponsors to create new message threads with a message type, subject, message body, and optional attachments
  • FR-002: System MUST require users to select exactly one message type when creating a thread
  • FR-003: System MUST route messages to appropriate recipients (organisers or admins) based on the selected message type
  • FR-004: System MUST support threaded conversations with chronological message history
  • FR-005: System MUST display message status indicators (new, read, replied, resolved)
  • FR-006: System MUST allow all participants in a thread to add responses (sponsor creator, any routed recipient team member, and event organiser) using a collaborative support model
  • FR-007: System MUST support file attachments up to 10MB per message
  • FR-008: System MUST preserve message context by linking messages to relevant entities (events, stands, artwork submissions)
  • FR-009: System MUST prevent changing the message type after a thread is created

Message Type Configuration

  • FR-010: System MUST provide admins with an interface to create and manage message types
  • FR-011: System MUST allow admins to configure a routing destination (recipient team) for each message type
  • FR-012: System MUST support at minimum two routing destinations: organisers and admins
  • FR-013: System MUST allow admins to set message types as active or inactive
  • FR-014: System MUST hide inactive message types from user selection but preserve them for existing threads
  • FR-015: System MUST validate message type configuration to ensure each type has a routing destination
  • FR-016: System MUST apply routing based on the message type selected at thread creation time
  • FR-017: System MUST provide default message types on system installation (e.g., "Event Query" → organisers, "Artwork Support" → admins, "Technical Issue" → admins)

Notification System

  • FR-018: System MUST generate notifications to all routed team members when a new message thread is created, respecting each user's notification preferences
  • FR-019: System MUST generate notifications to all thread participants when a response is added to an existing thread, respecting each user's notification preferences
  • FR-020: System MUST support multiple notification types beyond messaging (e.g., payment confirmations, deadline reminders, event updates, artwork approval status)
  • FR-021: System MUST deliver notifications through email channels when enabled
  • FR-022: System MUST deliver notifications through in-app channels when enabled
  • FR-023: System MUST persist in-app notifications indefinitely as unread if user lacks an active WebSocket connection and display them when user next logs in
  • FR-024: System MUST track notification delivery status (sent, delivered, read, failed)
  • FR-025: System MUST provide users with a notification history showing all past notifications

Notification Preferences

  • FR-026: System MUST allow users to configure notification preferences in their profile settings
  • FR-027: System MUST provide per-notification-type controls for email delivery
  • FR-028: System MUST provide per-notification-type controls for in-app delivery
  • FR-029: System MUST allow users to enable, disable, or configure both channels independently for each notification type
  • FR-030: System MUST save notification preference changes immediately and apply them to all future notifications
  • FR-031: System MUST provide reasonable default notification preferences for new users
  • FR-032: System MUST respect user preferences when generating notifications across all platform features, delivering only through channels enabled by each individual user

Real-Time In-App Notifications

  • FR-033: System MUST deliver in-app notifications in real-time to logged-in users without requiring page refresh
  • FR-034: System MUST use persistent connections for real-time notification delivery
  • FR-035: System MUST display notification count badges on relevant navigation elements
  • FR-036: System MUST display transient notification toasts when new notifications arrive
  • FR-037: System MUST update notification UI across all open browser tabs for the same user
  • FR-038: System MUST handle connection failures gracefully with reconnection behavior delegated to the frontend WebSocket provider
  • FR-039: System MUST fall back to polling or next-page-load notification display if real-time delivery fails
  • FR-040: System MUST mark notifications as read when user views the related content

Key Entities

  • Message Thread: Represents a conversation initiated by a user, containing a subject, message type, creation date, participants, status, and linked entity references (event, stand, artwork). Threads maintain chronological message history. Each thread has exactly one message type that cannot be changed after creation. Participants always include: the sponsor who created the thread, the routed recipient team (based on message type), and the event organiser for that event.

  • Message: Individual communication within a thread, containing sender, timestamp, message body, optional attachments, read status, and relationship to parent thread.

  • Message Type: System-configurable category that determines how messages are routed, containing type name, description, routing destination (organiser/admin team), active status, and display order. Examples: "Event Query", "Artwork Support", "Technical Issue", "Sponsorship Enquiry".

  • Notification: Record of an event requiring user attention, containing notification type, recipient, creation timestamp, delivery status, related content reference, read status, and delivery channels used.

  • Notification Preference: User-specific configuration defining how each notification type should be delivered, containing user reference, notification type, email enabled flag, in-app enabled flag, and last updated timestamp.

  • Notification Type: System-defined category of notifications (e.g., "New Message", "Payment Confirmation", "Deadline Reminder"), containing type identifier, display name, description, and default delivery settings.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: Sponsors can send a message and receive a response from the appropriate recipient within one business day for 90% of queries
  • SC-002: 95% of messages are automatically routed to the correct recipient type without requiring manual re-assignment
  • SC-003: Users receive in-app notifications within 2 seconds of the triggering event when logged in
  • SC-004: 80% of users configure at least one notification preference within their first week of using the platform
  • SC-005: Message threads maintain complete conversation history with zero message loss
  • SC-006: Users can locate and respond to messages within 3 clicks from any page in the platform
  • SC-007: System successfully delivers 99% of email notifications within 5 minutes of generation
  • SC-008: Notification preference changes take effect immediately for all subsequent notifications
  • SC-009: Real-time notification connections remain stable for 95% of user sessions without disconnection
  • SC-010: Users report improved communication satisfaction scores compared to external email-only communication

Assumptions (optional)

User Behaviour Assumptions

  • Users will select the appropriate message type when creating threads
  • Users will check the platform at least once per business day when active with an event
  • Users understand the difference between organisers (event-specific queries) and admins (technical support)
  • Users who disable all notification methods understand they are responsible for checking the platform regularly

System Context Assumptions

  • User authentication and session management are already implemented
  • User roles (sponsor, organiser, admin) are defined and enforced
  • File upload infrastructure exists for handling attachments
  • Email delivery service integration is available
  • Events, stands, and artwork entities exist and can be referenced by messages

Technical Assumptions

  • Modern browsers supporting WebSocket connections are used by majority of users
  • Email service has sufficient sending capacity for notification volumes
  • User devices have stable internet connections for real-time features
  • Platform has infrastructure to maintain persistent connections for real-time features
  • WebSocket reconnection logic is handled by the frontend WebSocket provider library

Configuration Assumptions

  • System will be installed with default message types: "Event Query" → organisers, "Stand Configuration Query" → organisers, "Artwork Support" → admins, "Technical Issue" → admins, "Payment Query" → admins
  • Default notification preferences for new users: all notification types enabled for both email and in-app
  • Attachments are limited to standard document and image formats (PDF, JPG, PNG, DOC, XLS)
  • Message history is retained for the lifetime of the associated event plus 12 months

Dependencies (optional)

Internal Dependencies

  • User Management System: Required for user authentication, role determination, and profile management
  • Event Management System: Required to link messages to specific events and identify event organisers
  • Permission System: Required to enforce access controls on message threads and routing configuration
  • File Storage System: Required for attachment upload, storage, and retrieval
  • Email Service Integration: Required for email notification delivery

External Dependencies

  • Email Service Provider: Service must support transactional email sending with tracking
  • Browser Support: Requires browsers with WebSocket support (all modern browsers)
  • Network Infrastructure: Requires stable network connectivity for real-time features

Constraints (optional)

Business Constraints

  • Messages must be retained for audit purposes for the duration of the event relationship
  • Admins are the only users permitted to configure message types and routing destinations
  • Message types cannot be changed after a thread is created to maintain audit trail
  • Notification preferences are user-controlled and cannot be overridden by admins (except for system-critical notifications)
  • Response time expectations: admins should respond to technical queries within 4 business hours; organisers should respond to event queries within 1 business day

Technical Constraints

  • File attachment size limited to 10MB per message
  • Supported attachment types limited to common business formats (no executable files)
  • Real-time notification delivery requires WebSocket support
  • Email sending subject to rate limits imposed by email service provider (typically 100-500 per hour for transactional emails)
  • Notification history retained for 90 days after being marked as read (unread notifications persist indefinitely)

User Experience Constraints

  • Message threads cannot be deleted by users (only marked as resolved/closed) to maintain audit trail
  • Message type cannot be changed after thread creation
  • Threads use collaborative support model - no assignment or locking mechanism required
  • Notification toasts should auto-dismiss after 5-8 seconds to avoid cluttering the interface
  • Maximum of 3 simultaneous notification toasts displayed to prevent UI overload
  • Message routing based solely on user-selected message type (no keyword analysis or AI-based classification)

Security and Privacy Constraints

  • Users can only view message threads they are participants in (sponsor creator, routed recipient team members, and event organiser for the associated event)
  • Attachments are scanned for malware before being made available
  • Message content is not indexed for full-text search to protect privacy (only subject lines and metadata)
  • Notification content in emails must not expose sensitive information beyond what's necessary to prompt user login