Overview

The chat module is the core user-facing feature of HyperSaaS. It provides a rich AI conversation interface with support for multiple providers, agent frameworks, knowledge base search, document viewer, and location mapping.

Component Architecture

ChatSessionUI (container)
    │
    ├── ChatSessionHeader
    │   ├── Session name + sidebar toggle
    │   ├── Document status badge
    │   ├── Map toggle
    │   └── Settings sheet trigger
    │
    ├── ResizablePanels (desktop)
    │   ├── Panel 1: MessageList
    │   ├── Panel 2: ChatMapGoogle (optional)
    │   └── Panel 3: ChatDocumentWorkspace (optional)
    │
    ├── ChatPromptInput
    │   ├── Textarea (Enter to send)
    │   ├── Language selector
    │   ├── Mic button (audio transcription)
    │   ├── Model selector
    │   └── Suggestions (empty chat only)
    │
    └── Floating Sheets
        ├── ChatSettingsForm (AI config + KB management)
        └── LocationDetailView (location info)

Chat Session Flow

1. User creates chat session
   ├── Select AI provider + model
   ├── Choose agent framework (LangGraph / PydanticAI / None)
   ├── Set system prompt + parameters
   └── Attach knowledge bases (optional)

2. User sends message (optionally with files)
   ├── POST /api/.../messages/stream/ (through the Next.js stream proxy)
   ├── Backend streams server-sent events
   │   ├── delta → reply text appears as it's written
   │   ├── tool  → tool steps show as they start and finish
   │   └── done  → the saved reply replaces the live one
   └── Stop ends the stream; the part written so far is kept

3. UI renders response
   ├── Markdown with syntax highlighting
   ├── Numbered inline citations linked to their sources
   ├── Location tags (clickable → map)
   ├── Tool call chain-of-thought (expandable)
   └── Map markers for locations

Key Features

Multi-Model Support

Users can switch models mid-conversation via the model selector dropdown:

The workspace's plan decides which of these a chat can use; choosing one the plan doesn't include shows the backend's message, such as "The Free plan doesn't include …".

Agent Frameworks

Selectable at session creation:

Knowledge Base RAG

When knowledge bases are attached to a session, the agent searches them before answering. The answer carries numbered inline citations, each linked to its source, listed below the response.

Streaming, Stop and Ratings

Replies stream token by token, including after an edit or a regenerate. A Stop button ends a reply early and keeps what was written. Assistant answers have thumbs-up and thumbs-down buttons, with an optional reason, saved per user.

When the backend refuses a message, the reason appears as a toast: rate limits ("You're sending messages too fast…"), used-up credit, a model the plan doesn't include, or a chat the user can only read.

Attachments

The message box accepts up to 5 files of up to 10 MB: images for models that can read them, and documents of the types the knowledge base accepts. They're sent with the message as multipart form data. Images in replies are shown as links rather than loaded.

Document Workspace

Clicking a citation opens the source document in a side panel. The PDF viewer highlights the relevant chunk, with page navigation.

Location Mapping

When the AI mentions locations, they appear as clickable tags in the message. Clicking a tag shows the location on the Google Maps panel.

Voice Input

The mic button records audio, sends it to the backend Whisper endpoint for transcription, and inserts the text into the prompt input.

Pages

Configuration

Chat sessions store their AI configuration:

Each model takes only some of these; the backend's model catalog says which, and sends nothing else. See the settings sheet.