Platform Overview

SupportGPT is a Next.js application backed by Supabase, Supabase Realtime, S3-compatible storage, model providers, and a hosted JavaScript widget.

Core Concepts

• Workspace: Team, plan, billing, message credits, members, and shared knowledge sources.
• Agent: Chat assistant configuration, model, instructions, widget settings, handoff settings, and actions.
• Sources: Files, text snippets, Q&A, crawled website pages, and Notion content stored as workspace files.
• Chunks: Extracted source text split into retrieval chunks and embedded with Gemini embeddings.
• Chat session: A visitor conversation with messages, source, visitor info, feedback, status, and handoff state.
• Live inbox: Human support workspace for escalated sessions.

Request Flow

flowchart LR
  V[Visitor]
  W[Embed script or iframe]
  A[Agent settings]
  R[Retrieval]
  M[Model provider]
  S[Supabase]
  I[Live Inbox]

  V --> W
  W --> A
  A --> R
  R --> S
  R --> M
  M --> W
  W --> S
  S --> I

Source Processing

When a source is added:

1. The dashboard sends the source to an authenticated upload or sync route.
2. The original file or extracted content is stored.
3. Text is extracted from supported formats.
4. Text is chunked for retrieval.
5. Chunks are embedded with gemini-embedding-001.
6. Chunks are stored in Supabase with pgvector.

Supported file text extraction currently includes PDF, DOCX, and TXT. The dashboard also accepts DOC files, but clean DOCX/TXT/PDF content is the safest source format.

Chat Response Flow

When a visitor sends a message:

1. The widget sends the message to the public embed chat route.
2. The route loads agent settings.
3. The route checks rate limits and identity data when available.
4. Workspace chunks are retrieved using the agent match threshold.
5. A grounded prompt is built with instructions, chat history, and source context.
6. The selected model provider returns the answer.
7. The message and session data are stored for analytics and logs.

Human Handoff Flow

Human handoff can be triggered by:

• The "Talk to Human" button.
• Configured trigger keywords.
• Negative sentiment patterns.
• Optional message count rules.

Escalated sessions appear in Agent -> Inbox. Supabase Realtime broadcasts new escalations and messages to active dashboard users.

Security And Identity

The widget can identify logged-in users with:

• userId.
• userHash, an HMAC generated on your server.
• user_metadata.email.
• user_metadata.name.

Use the secret key shown in Deploy -> Embed to generate the HMAC. Never place the secret key in browser code.

Current API Status

The dashboard and widget use Next.js API routes under /api. These routes require Supabase auth, service credentials, or public widget context depending on route. They are not a versioned public API contract.