Chat & Messaging
Direct messaging system between trainers and clients with real-time features including typing indicators, read receipts, online status, and file/image attachments.
Overview
The Chat & Messaging feature provides direct communication between trainers and their clients. It follows a standard messaging paradigm with a conversation list on the left and the active thread on the right (or as a full-screen view on mobile). Conversations support search, filtering by role (all/trainers/clients), unread count badges, and online status indicators.
Individual message threads display messages with timestamps, sender avatars, and alignment (sent messages on the right, received on the left). Real-time features include typing indicators, read receipts, and message delivery status. The system supports file and image attachments for sharing workout videos, progress photos, and training documents.
Messages are powered by Supabase Realtime for live updates without polling. The conversation list auto-updates when new messages arrive, and unread badges sync across all connected devices. Trainers can message any connected client, and clients can message their connected trainers.
User Stories
Client Stories
As a client, I want to message my trainer directly so that I can ask questions about my program, form, or nutrition.
As a client, I want to see when my trainer is online and typing so that I know when to expect a response.
As a client, I want to send progress photos and workout videos so that my trainer can provide form feedback.
As a client, I want to search my conversation history so that I can find past instructions or advice.
Trainer Stories
As a trainer, I want to manage conversations with all my clients from a single inbox so that I can efficiently respond to everyone.
As a trainer, I want to filter conversations by all, trainers, or clients so that I can focus on specific communication channels.
As a trainer, I want to see unread message counts and recent messages at a glance so that I never miss important client communications.
As a trainer, I want to share files and training documents with my clients so that I can provide supplementary materials.
Feature Details
Conversation List
- Search conversations by name
- Filter: All / Trainers / Clients
- Unread message count badges
- Online/offline status indicators
- Last message preview with timestamp
- Sorted by most recent activity
Message Thread
- Sender/receiver message alignment
- Timestamps on messages
- Read receipt indicators
- Typing indicator (animated dots)
- Auto-scroll to latest message
- Message input with send button
Attachments
- Image attachments with preview
- File attachments (PDF, documents)
- Video attachments
- Upload progress indicator
- File stored in Supabase Storage
- Thumbnail generation for images
Data Model
| Table | Key Columns | Description |
|---|---|---|
| conversations | id, participant_1_id, participant_2_id, last_message_at, last_message_preview, created_at | 1:1 conversation records between two users. Denormalized last message for list display. |
| messages | id, conversation_id, sender_id, content, attachment_url, attachment_type, is_read, read_at, created_at | Individual messages within conversations. Supports text and attachments. |
| user_presence | user_id, is_online, last_seen_at | Online status tracking via Supabase Realtime presence. |
Screens & Routes
| Route | File | Description |
|---|---|---|
| /messages | src/routes/_authed/_onboarded/messages.tsx | Messages page — conversation list + active thread (split pane on desktop, stack on mobile) |
Acceptance Criteria
Conversation List
Message Thread
Technical
API Surface
The messaging API is planned but not yet implemented. The current UI uses mock data from src/mocks/messages.ts.
Planned Server Functions
GET getConversations — List all conversations with last message preview
GET getMessages — Paginated messages for a conversation
POST sendMessage — Send text or attachment message
POST markAsRead — Mark all messages in conversation as read
GET getUnreadCount — Total unread message count for sidebar badge
POST startConversation — Create new conversation with a user
Realtime Subscriptions
SUBSCRIBE messages:conversation_id — New messages in active thread
SUBSCRIBE conversations:user_id — Conversation list updates
PRESENCE user_presence — Online status tracking
BROADCAST typing:conversation_id — Typing indicator events
Current Status
- Messages page UI layout
- Conversation list with mock data
- Message thread display
- Search bar in conversation list
- Filter tabs (All / Trainers / Clients)
- Online status indicators
- Mock data for conversations and messages
- Database schema for conversations and messages
- API server functions
- React Query hooks
- Supabase Realtime integration
- Typing indicators
- Read receipts
- File/image attachments
- Presence tracking
- Unread count badge in sidebar
- Message notifications