orion/docs/implementation/messaging-system.md

Messaging System Implementation

This document describes the messaging system that enables threaded conversations between different platform participants.

Overview

The messaging system supports three communication channels:

1. Admin <-> Store: Platform administrators communicate with store users
2. Store <-> Customer: Stores communicate with their customers
3. Admin <-> Customer: Platform administrators communicate with customers

Architecture

Database Models

Located in models/database/message.py:

Model	Description
Conversation	Threaded conversation container with subject, type, and status
ConversationParticipant	Links participants to conversations with unread tracking
Message	Individual messages within a conversation
MessageAttachment	File attachments for messages

Enums

Enum	Values	Description
ConversationType	admin_store, store_customer, admin_customer	Defines conversation channel
ParticipantType	admin, store, customer	Type of participant

Polymorphic Participants

The system uses polymorphic relationships via participant_type + participant_id:

• admin and store types reference users.id
• customer type references customers.id

Multi-Tenant Isolation

Conversations involving customers include a store_id to ensure proper data isolation. Store users can only see conversations within their store context.

Services

MessagingService (app/services/messaging_service.py)

Core business logic for conversations and messages:

Method	Description
create_conversation()	Create a new conversation with participants
get_conversation()	Get conversation with access validation
list_conversations()	Paginated list with filters
send_message()	Send message with automatic unread updates
mark_conversation_read()	Mark all messages read for participant
get_unread_count()	Get total unread count for header badge
close_conversation()	Close a conversation thread
reopen_conversation()	Reopen a closed conversation

MessageAttachmentService (app/services/message_attachment_service.py)

File upload handling:

Method	Description
validate_and_store()	Validate file type/size and store to disk
get_max_file_size_bytes()	Get limit from platform settings
delete_attachment()	Remove files from storage

Allowed file types:

• Images: JPEG, PNG, GIF, WebP
• Documents: PDF, Office documents
• Archives: ZIP
• Text: Plain text, CSV

Storage path pattern: uploads/messages/YYYY/MM/conversation_id/uuid.ext

API Endpoints

Admin API (/api/v1/admin/messages)

Endpoint	Method	Description
/messages	GET	List conversations
/messages	POST	Create conversation
/messages/unread-count	GET	Get unread badge count
/messages/recipients	GET	Get available recipients
/messages/{id}	GET	Get conversation detail
/messages/{id}/messages	POST	Send message (with attachments)
/messages/{id}/close	POST	Close conversation
/messages/{id}/reopen	POST	Reopen conversation
/messages/{id}/read	PUT	Mark as read
/messages/{id}/preferences	PUT	Update notification preferences

Store API (/api/v1/store/messages)

Same structure as admin, but with store context filtering. Stores can only:

• See their own store_customer and admin_store conversations
• Create store_customer conversations with their customers
• Not initiate admin_store conversations (admins initiate those)

Frontend

Admin Interface

• Template: app/templates/admin/messages.html
• JavaScript: static/admin/js/messages.js

Features:

• Split-panel conversation list + message thread
• Filters by type (stores/customers) and status (open/closed)
• Compose modal for new conversations
• File attachment support
• 30-second polling for new messages
• Header badge with unread count

Store Interface

• Template: app/templates/store/messages.html
• JavaScript: static/store/js/messages.js

Similar to admin but with store-specific:

• Only store_customer and admin_store channels
• Compose modal for customer conversations only

Pydantic Schemas

Located in models/schema/message.py:

• ConversationCreate - Create request
• ConversationSummary - List item with unread count
• ConversationDetailResponse - Full thread with messages
• ConversationListResponse - Paginated list
• MessageResponse - Single message with attachments
• AttachmentResponse - File metadata with download URL
• UnreadCountResponse - For header badge

Configuration

Platform Setting

The attachment size limit is configurable via platform settings:

• Key: message_attachment_max_size_mb
• Default: 10
• Category: messaging

Storefront (Customer) Interface

API Endpoints (/api/v1/storefront/messages)

Endpoint	Method	Description
/messages	GET	List customer's conversations
/messages/unread-count	GET	Get unread badge count
/messages/{id}	GET	Get conversation detail
/messages/{id}/messages	POST	Send reply message
/messages/{id}/read	PUT	Mark as read
/messages/{id}/attachments/{att_id}	GET	Download attachment

Frontend

• Template: app/templates/storefront/account/messages.html
• Page Route: /storefront/account/messages and /storefront/account/messages/{conversation_id}

Features:

• Conversation list with unread badges
• Filter by status (open/closed)
• Thread view with message history
• Reply form with file attachments
• 30-second polling for new messages
• Link from account dashboard with unread count

Limitations

Customers can only:

• View their store_customer conversations
• Reply to existing conversations (cannot initiate)
• Cannot close conversations

---

Future Enhancements

Email Notifications (Requires Email Infrastructure)

The messaging system is designed to support email notifications, but requires email infrastructure to be implemented first:

Prerequisites:

• SMTP configuration in settings (host, port, username, password)
• Email service (app/services/email_service.py)
• Email templates (app/templates/emails/)
• Background task queue for async sending

Planned Implementation:

1. MessageNotificationService (app/services/message_notification_service.py)

   • notify_new_message() - Send email to participants on new message
   • Respect per-conversation email_notifications preference
   • Include message preview and reply link

2. Email Template (app/templates/emails/new_message.html)

   • Subject: "New message: {conversation_subject}"
   • Body: Sender name, message preview, link to reply

3. Integration Points:

   • Call notify_new_message() from messaging_service.send_message()
   • Skip notification for sender (only notify other participants)
   • Rate limit to prevent spam on rapid message exchanges

Database Support: The email_notifications field on ConversationParticipant is already in place to store per-conversation preferences.

WebSocket Support (Optional)

Real-time message delivery instead of 30-second polling:

• Would require WebSocket infrastructure (e.g., FastAPI WebSocket, Redis pub/sub)
• Significant infrastructure changes

Migration

The messaging tables are created by migration e3f4a5b6c7d8_add_messaging_tables.py:

# Apply migration
alembic upgrade head

# Rollback
alembic downgrade -1

Navigation

Admin Sidebar

Messages is available under "Platform Administration" section.

Store Sidebar

Messages is available under "Sales" section.

Storefront Account Dashboard

Messages card is available on the customer account dashboard with unread count badge.

Header Badge

Both admin and store headers show an unread message count badge next to the messages icon.