Messages + Comments — Behavior

State machine

Messages don’t have a heavy lifecycle. The “states” derived from columns:

sent (created_at set) ──> read (read_at set)
                       └─> edited (edited_at set; not yet wired)
                       └─> deleted (deleted_at set)

There is no delivered state. The presence of a row in messages plus a WebSocket emit is the “sent” event; “delivered” is implicit (client got the WS push) and not persisted.

Invariants

Golden paths

Coach DMs a member

1. Coach opens /dashboard/messages, picks a member (membership row) from the conversation list or starts a new conversation.
2. Coach types content + optionally attaches an image (presigned PUT via POST /messages/upload-url, then PUT to R2).
3. POST /messages with { recipientMembershipId, content, attachmentIds: [...] }.
4. Service: validates pair, resolves attachments, inserts a messages row + message_attachments rows in a transaction, then:
   • Emits WS message:new to both user:{senderId} and user:{recipientId} rooms.
   • Enqueues push to the recipient via PushNotificationsService.notifyUser with category newMessage.

Member reads the conversation

1. Member opens chat → GET /conversations/:membershipId returns paginated history.
2. UI calls PUT /conversations/:membershipId/read → service bulk-updates read_at = now for unread messages where the member is the recipient.
3. Sender receives WS message:read for each updated message id.

Coach posts a workout comment

1. Coach opens member’s workout drawer → comments tab.
2. POST /workout-assignments/:assignmentId/comments with { content }.
3. Service: validates assignment access, inserts row with workout_assignment_id set. Fans out push to the OTHER participant (coach OR member depending on sender) with category newComment. Recipient is the assignment’s userId if sender is staff, otherwise the assigning coach.

Per-program comment summary

GET /programs/:programId/workout-comments/unread-count joins assignments through the workouts table to bucket unread comments to a program — surfaced as a badge on the program tab.

Edge cases

Side effects

Permissions