Skip to content

Chat

Purpose

The chat app provides realtime and asynchronous communication between:

  • internal organization users
  • customer organization users

It enables:

  • conversation-based messaging
  • file attachments
  • participant management
  • read tracking
  • realtime updates via websockets

The app is designed to support cross-tenant communication while keeping access strictly scoped through participants and org relationships.

Key concepts

Conversation

A conversation represents a communication channel between:

  • one internal org
  • one customer org

It may optionally be linked to a business context such as:

  • a report
  • a job
  • a ticket

Key properties:

  • UUID identifier
  • org-to-org relationship
  • optional topic reference
  • lifecycle (created / closed)

Participant

A participant represents a user in a conversation.

Key properties:

  • linked to a conversation
  • linked to a user
  • active/inactive state
  • role (optional, e.g. engineer, customer_user)
  • read tracking (last_read_at)

Participants define:

  • access control
  • visibility
  • realtime permissions

Message

A message is a unit of communication inside a conversation.

Key properties:

  • sender
  • body (text)
  • optional structured data
  • timestamps (created, edited, deleted)

Messages are:

  • append-only (with soft delete)
  • ordered by creation time
  • broadcast in realtime

MessageAttachment

Attachments are files associated with messages.

Key properties:

  • uploaded independently of messages
  • linked later to a message
  • file metadata (filename, type, size)

This enables:

  • upload-first workflows
  • reliable websocket message sending with attachments

Realtime events

The app supports websocket-based realtime communication.

Event types include:

  • message events (persistent)
  • typing events (ephemeral)

Entry points

URLs

Main REST endpoints include:

  • /chat/conversations/

  • list internal conversations

  • /portal/chat/conversations/

  • list customer conversations

  • /chat/conversations/create/

  • create new conversation

  • /chat/conversations/<id>/messages/

  • list messages (paginated)

  • /chat/conversations/<id>/attachments/upload/

  • upload attachment

  • /chat/conversations/<id>/read/

  • mark conversation as read

  • /chat/conversations/<id>/participants/

  • list participants

  • /chat/conversations/<id>/participants/add/

  • add participant

  • /chat/conversations/<id>/participants/<user_id>/remove/

  • remove participant

  • /chat/messages/<id>/edit/

  • edit message

  • /chat/messages/<id>/delete/

  • delete message

Websocket

Realtime endpoint:

  • /ws/chat/<conversation_id>/?token=<JWT>

Used for:

  • sending messages
  • receiving messages
  • typing indicators

Admin

Currently minimal or not explicitly defined.

Potential future use:

  • moderation
  • debugging conversations
  • attachment inspection

Tasks

Celery task:

  • cleanup_orphan_attachments

Purpose:

  • remove uploaded files that were never attached to messages
  • prevent storage leaks

Signals

Currently:

  • no explicit Django signals used

Future potential:

  • message-created hooks
  • participant changes
  • audit logging

Dependencies

Depends on

  • orgs
  • for organization and membership models

  • for internal/customer separation

  • authentication system

  • user model

  • JWT authentication

  • notifications

  • for notifying participants of new messages

  • channels

  • for websocket support

  • celery

  • for background cleanup tasks

Used by

  • frontend applications (web and mobile)
  • for chat UI
  • conversation lists

  • realtime updates

  • potentially other backend apps

  • linking conversations to domain entities (future)

Operational notes

Known pitfalls

  • websocket auth relies on query token

  • must be handled securely on frontend

  • participant checks are critical

  • missing checks can expose conversations

  • attachment lifecycle is two-step

  • upload first, then attach via message

  • orphan cleanup is required

  • internal vs customer org separation

  • must always be respected in queries and permissions

Performance considerations

  • message queries are paginated

  • prevents loading full history

  • indexes on:

  • conversation + created_at

  • org relationships

  • websocket groups scale per conversation

  • large conversations may increase broadcast load

  • attachment cleanup task prevents storage bloat

  • unread counts are computed dynamically

  • may need optimization for very large datasets

Frontend readiness notes

The backend already supports:

  • REST-based conversation and message retrieval
  • websocket-based realtime messaging
  • attachment upload and linking

Frontend integration should follow:

  1. load conversations via REST
  2. load message history via REST
  3. connect websocket per conversation
  4. send messages via websocket
  5. upload attachments via REST before sending message
  6. mark read via REST

Security considerations

  • only participants may:
  • connect to websocket
  • read messages
  • upload attachments

  • modify messages

  • JWT authentication is required for websocket access

  • org linkage is enforced for conversation creation

Summary

The chat app provides a complete messaging system with:

  • conversation-based structure
  • participant-driven access control
  • realtime websocket communication
  • attachment support
  • read tracking
  • clean separation of concerns across layers

It is backend-complete and ready to be integrated into frontend clients.