Skip to main content

Messaging & Notifications System

Status: ✅ Core Features Complete
Last Updated: 2026-01-19

Overview​

Unified messaging and notification center that consolidates all user communications and notifications in one place, with an email client-like interface. Supports direct messaging, project/group invites, system notifications, rich content embeds, and comprehensive privacy controls.

Implementation Details​

Core Messaging Infrastructure​

  • ✅ Database schema (Message, MessageCategory enum, MessageRichContent JSON field, ProjectInvite, ProjectMember, GroupInvite models)
  • ✅ MessageService with create, get, mark as read/unread, archive/delete, search, handle invite acceptance/decline
  • ✅ MessageRichContentService for generating embeds (project, group, task, user, achievement, battle result) and action buttons
  • ✅ MessageLinkParserService for automatic link parsing and embed conversion
  • ✅ Markdown validation and sanitization (validateMarkdown, sanitizeMarkdown utilities)
  • ✅ Comprehensive test coverage (25 validation tests, 8 MessageService integration tests, 33 MessageRichContentService tests)

Direct Messaging​

  • ✅ Send messages to users (by userId, publicId, or email)
  • ✅ Send messages to yourself (for notes/reminders)
  • ✅ Send messages to linked users (via PersonArcLink)
  • ✅ Privacy enforcement (respects recipient's privacy settings)
  • ✅ Dual delivery (in-app + email notifications)
  • ✅ Threaded conversations (getConversations, getConversation, replyToMessage)
  • ✅ Read receipts (shows when recipient has read message)
  • ✅ Message reactions (emoji reactions)
  • ✅ Message forwarding
  • ✅ Message search within conversations
  • ✅ Message attachments (files, images)

Rich Content Support​

  • ✅ Markdown rendering (full markdown support with react-markdown, syntax highlighting with highlight.js)
  • ✅ Safe markdown parsing (sanitize HTML, prevent XSS with rehype-sanitize)
  • ✅ Action buttons (Accept/Decline, Join Project, etc.)
  • ✅ Embeds: Project, Group, Task, User, Achievement, Battle Result, Character, Character Stats, Leaderboard
  • ✅ Message templates (7 templates: project-invite, group-invite, task-assignment, achievement-celebration, battle-result, weekly-recap, simple-note)
  • ✅ Automatic link parsing (converts internal ARC links to embeds)

Invite System​

  • ✅ ARC link invites (from PersonArcLinkService)
  • ✅ Project invitations (invite users to collaborate on projects)
  • ✅ Group invitations (invite users to join groups)
  • ✅ Accept/decline invites directly from messaging center
  • ✅ Deeplinking support (project invites, group invites, ARC link invites, user profile deeplinks)
  • ✅ Project collaboration (ProjectMember table, members can view/edit project tasks)

Notification System​

  • ✅ NotificationService with generateDailyRecap, generateWeeklyRecap, sendAchievementNotification, sendLevelUpNotification
  • ✅ NotificationPreferencesService (per-category preferences for showInMessagingCenter, sendEmail, frequency)
  • ✅ Event announcements (system messages sent when events start)
  • ✅ Notification icon in top navigation (badge with unread count, dropdown menu with recent notifications)

User Discovery & Privacy​

  • ✅ Public user ID system (user-friendly format based on email)
  • ✅ User search by public ID or email (respects privacy settings)
  • ✅ Public profile pages (/user/:publicId or /user/by-email/:email)
  • ✅ Privacy controls (publicIdVisibility, emailSearchVisibility, publicProfileVisibility)
  • ✅ Mutual connections display

Frontend Components​

  • ✅ MessagingPage (list view, detail view, folder navigation, filters, search)
  • ✅ MessageCard (preview, quick actions, embed previews)
  • ✅ MessageDetail (full message content, action buttons, rich content rendering)
  • ✅ MarkdownRenderer (GitHub Flavored Markdown, syntax highlighting, HTML sanitization)
  • ✅ MessageEmbed components (ProjectEmbed, GroupEmbed, TaskEmbed, UserEmbed, AchievementEmbed, BattleResultEmbed)
  • ✅ MessageButton (styled action buttons with loading states)
  • ✅ NotificationIcon (badge, dropdown menu, quick actions)
  • ✅ ComposeMessagePage (recipient search, markdown editor, preview mode)
  • ✅ ConversationView (threaded conversation, reply functionality, read receipts)
  • ✅ InviteUserModal (reusable for projects and groups)
  • ✅ PublicUserProfilePage (public profile display, mutual connections, actions)

Design​

  • ✅ Monochrome aesthetic (matches ARC design system)
  • ✅ Email client inspiration (Gmail, Outlook - folder sidebar, list/detail split view)
  • ✅ Responsive design (comprehensive mobile/tablet breakpoints)
  • ✅ Keyboard shortcuts (j/k navigation, Enter to open, a to archive, r to reply, c to compose)
  • ✅ Accessibility (ARIA labels, keyboard navigation)

API Endpoints​

  • GET /api/messages - List messages with filters
  • GET /api/messages/:id - Get message details
  • POST /api/messages/:id/read - Mark as read
  • POST /api/messages/:id/unread - Mark as unread
  • POST /api/messages/:id/archive - Archive message
  • POST /api/messages/:id/unarchive - Unarchive message
  • DELETE /api/messages/:id - Delete message
  • GET /api/messages/unread-count - Get unread count for notification badge
  • POST /api/messages/:id/accept - Accept invite (ARC link, project, group)
  • POST /api/messages/:id/decline - Decline invite
  • POST /api/messages - Send direct message
  • GET /api/messages/conversations - Get conversation threads
  • GET /api/messages/conversations/:userId - Get conversation with specific user
  • POST /api/messages/:id/reply - Reply to message
  • POST /api/messages/:id/reactions - Add message reaction
  • DELETE /api/messages/:id/reactions/:reactionId - Remove message reaction
  • POST /api/messages/:id/forward - Forward message
  • POST /api/messages/:id/attachments - Upload message attachment
  • GET /api/messages/:id/attachments - Get message attachments
  • DELETE /api/messages/:id/attachments/:attachmentId - Delete message attachment
  • POST /api/projects/:projectId/invite - Invite user to project
  • GET /api/projects/:projectId/invites - Get pending invites for project
  • GET /api/projects/:projectId/members - Get project members
  • DELETE /api/projects/:projectId/members/:memberUserId - Remove project member
  • POST /api/notifications/daily-recap - Generate and send daily recap
  • POST /api/notifications/weekly-recap - Generate and send weekly recap
  • GET /api/notification-preferences - Get notification preferences
  • PUT /api/notification-preferences - Update notification preferences
  • GET /api/messages/by-project-invite/:inviteId - Get message by project invite ID
  • GET /api/messages/by-group-invite/:inviteId - Get message by group invite ID
  • GET /api/messages/by-link/:linkId - Get message by ARC link ID
  • GET /api/messages/validate-project-invite/:inviteId - Validate project invite
  • GET /api/messages/validate-group-invite/:inviteId - Validate group invite
  • GET /api/v1/users/search - Search users by publicId or email
  • GET /api/v1/users/:publicId - Get public user profile
  • GET /api/v1/users/by-email/:email - Find user by email
  • GET /api/v1/users/public-id/suggest - Get suggested public ID
  • PUT /api/v1/users/public-id - Set/update public ID
  • GET /api/v1/users/privacy - Get privacy settings
  • PATCH /api/v1/users/privacy - Update privacy settings
  • GET /api/message-templates - List message templates
  • GET /api/message-templates/:id - Get message template
  • POST /api/message-templates/:id/render - Render message template

Frontend Pages​

  • Messaging Center (/messages)
  • Compose Message (/messages/compose)
  • Conversation View (/messages/conversations/:userId)
  • Public User Profile (/user/:publicId or /user/by-email/:email)