​

System architecture

​

High-level flow

User/Widget -> Chat API or WebSocket -> Auth middleware -> Intent service
          -> Action service -> External integration (e.g. Shopify)
          -> Response formatter -> Conversation storage -> Client response
                           \-> Escalation service -> Ticket + audit logs

​

Core backend modules

​

Tenant isolation model

• conversations
• tickets
• intents
• integrations
• audit logs
• settings

​

Request lifecycle (Chat HTTP)

1. Auth middleware validates token and attaches auth context.
2. Message is written to messages table.
3. Recent conversation history is loaded for context.
4. Intent is detected with confidence score + entities.
5. If confidence low or missing intent -> escalation workflow.
6. Otherwise action executes and response is formatted.
7. Assistant message and metadata are persisted.
8. API returns assistant response + metadata.

​

Request lifecycle (Admin HTTP)

1. Supabase token is validated.
2. User is mapped to tenant via admin_users.
3. Route handler loads/updates tenant-scoped records.
4. Mutations write audit log entries.
5. Response returns filtered, tenant-scoped objects.

​

Real-time lifecycle (WebSocket)

1. Client connects with token query string.
2. Server authenticates token and replies connected.
3. Client sends message, typing, history, or ping events.
4. Server streams or returns message responses.
5. Heartbeat (ping/pong) keeps sessions healthy.