sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: migrate module documentation to single source of truth

Browse Source 
Move 39 documentation files from top-level docs/ into each module's
docs/ folder, accessible via symlinks from docs/modules/. Create
data-model.md files for 10 modules with full schema documentation.
Replace originals with redirect stubs. Remove empty guide stubs.

Modules migrated: tenancy, billing, loyalty, marketplace, orders,
messaging, cms, catalog, inventory, hosting, prospecting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2026-03-08 23:38:37 +01:00
parent 2287f4597d
commit f141cc4e6a
140 changed files with 19921 additions and 17723 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
docs/implementation/messaging-system.md
View File

@@ -1,243 +1 @@
# 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`:
```bash
# 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.
This document has moved to the messaging module docs: [Messaging Architecture](../modules/messaging/architecture.md)