# Chatty: Comprehensive Technical Documentation & Platform Manual
Welcome to the complete technical documentation for **Chatty** — the enterprise conversational AI, live omnichannel helpdesk, intelligent scheduling, and support platform.
---
## Table of Contents
1. [System Architecture & Tech Stack](#1-system-architecture--tech-stack)
2. [Database Schema & Data Models](#2-database-schema--data-models)
3. [The 21 Dashboard Modules](#3-the-21-dashboard-modules)
4. [Widget SDK & Embed Engine](#4-widget-sdk--embed-engine)
5. [Conversational AI Brain & RAG Engine](#5-conversational-ai-brain--rag-engine)
6. [Visual Flow Architect & AI Copilot](#6-visual-flow-architect--ai-copilot)
7. [Enterprise Knowledge Base & Help Center](#7-enterprise-knowledge-base--help-center)
8. [Omnichannel Live Inbox & SLA Routing](#8-omnichannel-live-inbox--sla-routing)
9. [Intelligent Calendar & Meeting Booking](#9-intelligent-calendar--meeting-booking)
11. [Complete REST API Reference](#11-complete-rest-api-reference)
12. [Model Context Protocol (MCP) Server](#12-model-context-protocol-mcp-server)
13. [Webhooks & Events Reference](#13-webhooks--events-reference)
14. [Security, BYOK & Permissions](#14-security-byok--permissions)
15. [Deployment, DevOps & Mirroring Guide](#15-deployment-devops--mirroring-guide)
---
## 1. System Architecture & Tech Stack
Chatty is built as a cloud-native, real-time distributed application designed for multi-tenant scalability, high availability, and ultra-low latency.
```mermaid
graph TB
subgraph Clients["Clients & Embeds"]
WebDash["Next.js 15 App Router Dashboard
(chatty.personaliai.com)"]
WidgetReact["@personaliai/react-widget
(ChatWidgetCore)"]
WidgetScript["Standalone Embed Script
(chatty-app.js)"]
KBPortal["Public Knowledge Base & Help Center
(/kb/[botId])"]
end
subgraph BackendServices["Backend Microservices (api.chatty.personaliai.com)"]
FastAPI["FastAPI Core Engine"]
WidgetBrain["Widget Brain & Agent Tool Loop"]
AvailabilityEngine["Availability & Round-Robin Meeting Engine"]
DocRAG["Document Indexing & Semantic Vector RAG"]
MCPRouter["Model Context Protocol (MCP) Server"]
end
subgraph DataLayer["Storage & External Services"]
Supabase["Supabase PostgreSQL 15+
(pgvector, Auth, Realtime, Storage)"]
LLMs["Multi-Provider LLMs
(Gemini, OpenAI, Anthropic, Groq, BYOK)"]
Calendars["Google Calendar & Outlook 365 (OAuth2)"]
Payments["Stripe / Lemon Squeezy"]
Webhooks["HMAC-SHA256 Outbound & Inbound Email (Resend)"]
end
Clients --> FastAPI
FastAPI --> WidgetBrain
FastAPI --> AvailabilityEngine
FastAPI --> DocRAG
FastAPI --> MCPRouter
FastAPI --> Supabase
WidgetBrain --> LLMs
DocRAG --> Supabase
AvailabilityEngine --> Calendars
FastAPI --> Payments
FastAPI --> Webhooks
```
### Core Technologies
- **Frontend & Admin Dashboard**:
- **Framework**: Next.js 15 (App Router, Turbopack, Server Actions, React 19).
- **Styling**: Tailwind CSS v4, Framer Motion animations, Radix UI / Base UI primitives, Lucide icons.
- **Data Visualization**: Leaflet / React-Leaflet (Visitor Geospatial Map), KaTeX (LaTeX math rendering), Cytoscape / React Flow (Flow Architect).
- **State & Realtime**: Supabase SSR client with PostgreSQL real-time change subscriptions.
- **Backend API & Microservices**:
- **Framework**: Python 3.11+, FastAPI, Uvicorn, Pydantic v2.
- **Security**: Fernet AES-128-CBC symmetric encryption (BYOK & OAuth tokens), HMAC-SHA256 webhook signatures, JWT verification, granular CORS, Request-ID tracing.
- **Observability**: Sentry SDK with distributed tracing and performance profiling.
- **AI & RAG Infrastructure**:
- **Primary Models**: Google Gemini 2.5 Flash / 3.x Flash-Lite, OpenAI GPT-4o / GPT-4o-mini, Anthropic Claude 3.5 Sonnet / Haiku, Groq Llama 3.3 70B.
- **Embeddings**: Google `text-embedding-004` (768 dimensions) & OpenAI `text-embedding-3-small` (1536 dimensions).
- **Vector Database**: PostgreSQL with `pgvector` extension and HNSW indexing for sub-millisecond semantic retrieval.
---
## 2. Database Schema & Data Models
The database is built on PostgreSQL via Supabase, protected by Row Level Security (RLS), custom database functions, and foreign-key constraints.
```mermaid
erDiagram
chatty_bots ||--o{ chatty_sessions : "has many"
chatty_bots ||--o{ chatty_sources : "indexes"
chatty_bots ||--o{ chatty_documents : "contains"
chatty_bots ||--o{ chatty_team_members : "manages"
chatty_bots ||--o{ chatty_meetings : "schedules"
chatty_bots ||--o{ chatty_leads : "captures"
chatty_bots ||--o{ chatty_webhooks : "dispatches"
chatty_bots ||--o{ chatty_kb_collections : "organizes"
chatty_bots ||--o{ chatty_agent_presence : "tracks"
chatty_bots ||--o{ chatty_api_keys : "authenticates"
chatty_sessions ||--o{ chatty_conversations : "contains"
chatty_sessions ||--o{ chatty_session_notes : "annotated by"
chatty_sessions ||--o{ chatty_csat_feedback : "rated by"
chatty_kb_collections ||--o{ chatty_kb_articles : "groups"
```
### Table Dictionary
#### `chatty_bots`
The root bot entity representing an AI agent instance.
- `id` (`uuid`, PK): Bot identifier.
- `user_id` (`uuid`, FK -> auth.users): The bot creator/owner.
- `name` (`text`): Display name of the bot.
- `system_prompt` (`text`): Master behavioral instruction prompt injected into LLM context.
- `model` (`text`): Active LLM model (e.g. `gemini-2.5-flash`, `gpt-4o`).
- `temperature` (`float`): Sampling temperature (0.0 to 1.0).
- `color_scheme` (`jsonb`): Widget color theme, hex codes, auto-contrast tokens.
- `avatar_url` (`text`): Custom avatar image URI or preset icon identifier.
- `launcher_style` (`text`): Widget launcher type (`bubble`, `bar`, `tab`, `inline`).
- `panel_size` (`text`): Dimensions (`compact`, `standard`, `spacious`, `fullscreen`).
- `allowed_domains` (`text[]`): Domain origin allowlist for embed widgets.
- `notification_emails` (`text[]`): Recipient list for instant lead and handoff alerts.
- `csat_enabled` (`boolean`): Whether to display post-chat CSAT star rating widget.
#### `chatty_sessions`
Represents an individual visitor ticket or omnichannel conversation thread.
- `id` (`uuid`, PK): Internal row ID.
- `session_id` (`text`, Unique per bot): Visitor session ID (`v-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).
- `bot_id` (`uuid`, FK -> chatty_bots): Associated bot.
- `status` (`text`): Lifecycle status (`open`, `pending`, `resolved`, `closed`).
- `priority` (`text`): Helpdesk priority (`urgent`, `high`, `normal`, `low`).
- `channel` (`text`): Ingress channel (`web`, `email`, `whatsapp`).
- `visitor_name` (`text`): Identified visitor name.
- `visitor_email` (`text`): Identified visitor email.
- `assigned_agent_email` (`text`, Nullable): Currently assigned team member email.
- `assigned_agent_name` (`text`, Nullable): Assigned agent display name.
- `ai_paused` (`boolean`): When `true`, AI generation is suspended for live human takeover.
- `needs_attention` (`boolean`): Flag raised when visitor requests human escalation or sentiment drops.
- `escalation_reason` (`text`, Nullable): Reason for human handoff.
- `sla_status` (`text`): SLA compliance state (`on_track`, `breached`, `met`).
- `first_response_due_at` (`timestamptz`): SLA deadline for first agent response.
- `first_responded_at` (`timestamptz`): Actual timestamp of first agent message.
- `resolution_due_at` (`timestamptz`): SLA deadline for full ticket resolution.
- `resolved_at` (`timestamptz`): Timestamp when ticket was marked resolved.
- `tags` (`text[]`): Custom organizational tags.
- `last_message` (`text`): Snippet of the most recent message.
- `last_message_at` (`timestamptz`): Timestamp of latest message activity.
#### `chatty_conversations`
Individual chat messages belonging to a session.
- `id` (`uuid`, PK): Message ID.
- `session_id` (`text`): Associated session identifier.
- `bot_id` (`uuid`, FK -> chatty_bots): Associated bot.
- `sender` (`text`): Message author (`user`, `bot`, `agent`, `system`).
- `text` (`text`): Content payload (supports Markdown, LaTeX math, code blocks).
- `audio_url` (`text`, Nullable): Voice message recording URL if voice message.
- `feedback` (`int2`, Nullable): User reaction rating (`1` for thumbs up, `-1` for thumbs down).
- `created_at` (`timestamptz`): Timestamp created.
#### `chatty_session_notes`
Internal collaboration notes viewable only by staff members.
- `id` (`uuid`, PK): Note ID.
- `session_id` (`text`): Associated session identifier.
- `bot_id` (`uuid`, FK -> chatty_bots): Associated bot.
- `author_email` (`text`): Staff member email who created the note.
- `author_name` (`text`): Staff member display name.
- `note` (`text`): Internal note text.
- `created_at` (`timestamptz`): Creation timestamp.
#### `chatty_agent_presence`
Tracks real-time online status and live ticket workload of human agents.
- `id` (`uuid`, PK): Presence ID.
- `bot_id` (`uuid`, FK -> chatty_bots): Associated bot.
- `agent_email` (`text`): Agent email.
- `agent_name` (`text`): Agent name.
- `status` (`text`): Presence state (`online`, `busy`, `away`, `offline`).
- `max_capacity` (`int`): Maximum concurrent active tickets (default `5`).
- `active_tickets_count` (`int`): Live count of open/pending tickets assigned to agent.
- `last_seen_at` (`timestamptz`): Last heartbeat ping from dashboard.
- `last_assigned_at` (`timestamptz`): Timestamp of most recent ticket assignment (for round-robin balance).
#### `chatty_routing_settings`
Configures automatic ticket dispatching and load balancing rules.
- `bot_id` (`uuid`, PK, FK -> chatty_bots): Associated bot.
- `routing_strategy` (`text`): Strategy (`round_robin`, `least_loaded`, `skill_based`).
- `auto_assign_enabled` (`boolean`): Whether incoming tickets are automatically dispatched.
- `reassign_on_offline` (`boolean`): Reassign tickets if agent goes offline.
- `offline_timeout_minutes` (`int`): Inactivity minutes before an agent is considered offline.
#### `chatty_team_members`
Team roster and granular permissions matrix.
- `id` (`uuid`, PK): Membership ID.
- `bot_id` (`uuid`, FK -> chatty_bots): Associated bot.
- `email` (`text`): Team member email.
- `name` (`text`): Team member name.
- `role` (`text`): High-level role (`owner`, `admin`, `agent`).
- `permissions` (`text[]`): Array of accessible dashboard tabs (`inbox`, `sources`, `design`, `settings`, `voice`, `team`, `meetings`).
- `bookable` (`boolean`): Whether this agent is eligible to receive booked calendar meetings.
- `book_on_own_calendar` (`boolean`): Whether appointments sync to their own connected calendar vs. bot primary calendar.
#### `chatty_meetings`
Appointments booked through the chatbot.
- `id` (`uuid`, PK): Meeting ID.
- `bot_id` (`uuid`, FK -> chatty_bots): Associated bot.
- `session_id` (`text`, Nullable): Associated chat session.
- `provider` (`text`): Calendar provider (`google`, `microsoft`, `calcom`).
- `provider_event_id` (`text`): Upstream calendar event ID.
- `assigned_agent_email` (`text`): Agent assigned to host the meeting.
- `start_time` (`timestamptz`): Meeting start time.
- `end_time` (`timestamptz`): Meeting end time.
- `timezone` (`text`): Attendee timezone (e.g. `America/New_York`, `Asia/Colombo`).
- `attendee_name` (`text`): Visitor full name.
- `attendee_email` (`text`): Visitor email.
- `attendee_phone` (`text`, Nullable): Visitor phone.
- `meeting_link` (`text`, Nullable): Google Meet, Teams, or Zoom URL.
- `status` (`text`): Status (`confirmed`, `rescheduled`, `cancelled`).
#### `chatty_scheduling_settings`
Working hours and calendar constraints.
- `bot_id` (`uuid`, PK, FK -> chatty_bots): Associated bot.
- `working_hours` (`jsonb`): Day-by-day availability schedules (e.g. Mon-Fri 09:00-17:00).
- `slot_duration_minutes` (`int`): Meeting duration (e.g. 15, 30, 45, 60 minutes).
- `buffer_minutes` (`int`): Padding before and after meetings.
- `min_notice_hours` (`int`): Minimum advance notice required to book (e.g. 2 hours).
- `max_days_out` (`int`): Maximum booking horizon (e.g. 14 days).
- `max_meetings_per_day` (`int`): Daily meeting cap to prevent burnout.
#### `chatty_sources` & `chatty_documents`
Vector-indexed knowledge base resources.
- `chatty_sources`: High-level source (URL website crawl, sitemap, or file upload batch).
- `id` (`uuid`, PK), `bot_id`, `type` (`url`, `sitemap`, `file`, `qa`), `url`, `status` (`indexing`, `indexed`, `failed`), `crawl_schedule` (`manual`, `daily`, `weekly`).
- `chatty_documents`: Individual text chunks and vector embeddings.
- `id` (`uuid`, PK), `source_id`, `bot_id`, `title`, `content` (`text`), `token_count` (`int`), `embedding` (`vector(768)` or `vector(1536)`).
#### `chatty_kb_collections` & `chatty_kb_articles`
Enterprise public Help Center documentation portal.
- `chatty_kb_collections`: Categories / Knowledge hubs (e.g. "Getting Started", "Billing & Plans").
- `id` (`uuid`, PK), `bot_id`, `title`, `description`, `icon`, `slug`, `order_index`.
- `chatty_kb_articles`: Individual Help Center articles.
- `id` (`uuid`, PK), `collection_id`, `bot_id`, `title`, `slug`, `content` (`text`, rich markdown/HTML), `views` (`int`), `helpful_votes` (`int`), `unhelpful_votes` (`int`), `published` (`boolean`).
#### `chatty_leads`
Captured prospect records.
- `id` (`uuid`, PK), `bot_id`, `session_id`, `name`, `email`, `phone`, `company`, `custom_fields` (`jsonb`), `ip_address`, `country`, `city`, `latitude`, `longitude`, `created_at`.
#### `chatty_webhooks` & `chatty_webhook_deliveries`
Event notification system.
- `chatty_webhooks`: Subscribed endpoints with HMAC signing secrets.
- `chatty_webhook_deliveries`: Delivery audit logs with HTTP response status, execution duration, and automatic retry attempts.
---
## 3. The 21 Dashboard Modules
The Chatty Dashboard (`/dashboard`) delivers an all-in-one suite across 21 specialized views:
| Module | Identifier | Key Functions |
| :--- | :--- | :--- |
| **1. Home** | `home` | Real-time overview, total tickets, deflection rate, lead counts, bot health scorecard. |
| **2. Customizer** | `customizer` | Live interactive widget designer: 5 launcher styles, avatar upload, themes, color contrast scoring, panel sizing. |
| **3. Knowledge** | `knowledge` | RAG ingestion hub: URL crawler, sitemap parser, PDF/DOCX/TXT uploader, enterprise Help Center article editor. |
| **4. Playground** | `playground` | Interactive developer test sandbox with prompt modification, live RAG inspection, and debug tokens. |
| **5. Inbox** | `inbox` | Live helpdesk: Ticket queuing, status filtering, SLA countdown clocks, presence roster, auto-dispatch. |
| **6. Flows** | `flows` | Visual Flow Architect: Canvas-based node editor with AI Copilot for branching conversation flows. |
| **7. Campaigns** | `campaigns` | Proactive popups, teaser messages, behavioral triggers, exit-intent detection, page URL matching. |
| **8. Leads** | `leads` | Lead CRM table: Dynamic columns, geolocation details, conversation transcripts, CSV export. |
| **9. Feedback** | `feedback` | CSAT analytics: 1-5 star ratings, feedback breakdown, customer sentiment trends. |
| **10. Map** | `map` | Interactive geospatial world map displaying visitor distribution and regional density. |
| **11. Meetings** | `meetings` | Booked appointments calendar: Google Meet / Outlook links, attendee data, cancellation management. |
| **13. Mailbox** | `mailbox` | Inbound email ticketing: Postmark/Resend webhook ingestion, customer email threading, staff email replies. |
| **14. Notifications** | `notifications` | Alert dispatcher: Configure instant alerts to Slack, Discord, Telegram, or Webhooks for new leads and tickets. |
| **15. Audit Log** | `audit_log` | Security audit trail: Searchable, immutable record of staff logins, bot edits, API requests, and data exports. |
| **16. Analytics** | `analytics` | Performance charts: Message volume, deflection rates, average resolution time, token consumption. |
| **17. Integrations** | `integrations` | External calendar OAuth connectors (Google Calendar, Microsoft Outlook, Cal.com), Zapier webhooks. |
| **18. Developer** | `developer` | API key management (SHA-256 hashed), usage quotas, interactive OpenAPI Swagger explorer. |
| **19. MCP** | `mcp` | Model Context Protocol server configuration allowing Cursor and Claude Desktop to execute Chatty tools. |
| **20. Billing** | `billing` | Subscription management (Hobby, Standard, Business, Enterprise), invoice downloads, quota limits. |
| **21. Settings** | `settings` | Core bot parameters: LLM model selection, temperature, guardrails, allowed domains, BYOK encryption keys. |
---
## 4. Widget SDK & Embed Engine
The Chatty widget can be embedded into any website or application using either the lightweight script loader or the official React component.
### Script Embed (Vanilla HTML, WordPress, Webflow, Shopify)
Add this script snippet before the closing `` tag:
```html