Glow Overview

PreviousNext

Overview of the Glow AI Chat System

What is Glow?

Glow is a structured AI chat system that powers conversational flows on Zooly. It enables guided, graph-based conversations where the AI assistant follows a defined flow (nodes and edges), uses context-specific tools, and can switch between different conversation contexts.

Purpose

The Glow system enables:

  • Structured conversation flows - Graph-based flows defined in Mermaid syntax with nodes and transitions
  • Context-aware tools - Tools are scoped to the current node; the AI can only use tools available in the current context
  • Context switching - Chats can switch between different flows (e.g., from "backstage" to "support") via changeChatContext and returnToContext
  • Response caching - Similar questions can be answered from cache using embedding similarity (when enabled)
  • Rich UI tools - Built-in tools for image/video/audio upload, buttons, ratings, memory, and custom API calls

Key Concepts

Glow Settings (Flow Configuration)

Each flow is defined by GlowSettings:

  • slug - Unique identifier (e.g., backstage-mini-app, support)
  • glowName - Display name for the flow
  • glowPrompt - High-level description of the flow
  • glowMermaidChart - Graph definition in Mermaid syntax (nodes and edges)
  • nodesMetadata - Per-node metadata: label, fields, system instructions, and available tools
  • enableCache - Whether to cache similar questions for faster responses

Glow Chat (Session)

A GlowChat represents a chat session:

  • glowCurrentSlug - The flow the chat is currently in
  • currentNodeId - The current node in the flow (determines available tools)
  • messages - Conversation history (user + assistant messages)
  • clientMsgState - Client-side state (e.g., form data, tool outputs) keyed by message/part

Node Metadata

Each node in the flow has metadata:

  • id - Node identifier
  • label - Human-readable description
  • fields - Key-value config (e.g., systemInstructions)
  • tools - Map of tool names to minimal tool definitions (name, description, fields)

Tools

Tools are either:

  • UI tools - Rendered by the client (e.g., askUserToUploadImage, askUserToChooseOptionWithBtns)
  • API tools - Server-side calls to external APIs (defined in glow_tool table with urlApi)

The AI can only use tools specified in the current node's metadata.

System Architecture

┌─────────────────────────────────────────────┐
│   App (zooly-app)                           │
│   API routes: /api/glow-chat-client/*      │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│   @zooly/glow-server                        │
│   handleGlowChatStream, handleGlowChatCore  │
│   handleGlowChatWithCache, getOrCreateGlowChat │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│   @zooly/glow-client                        │
│   GlowChatClient, GlowAIProvider            │
│   useGlowChat, TOOL_REGISTRY                 │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│   @zooly/db                                 │
│   glow_chat, glow_settings, glow_tool        │
│   cached_answer_state, question_cache       │
└─────────────────────────────────────────────┘

Flow Execution

  1. User sends message - Client POSTs to /api/glow-chat-client with messages and glowChatId
  2. Cache check (if enabled) - Server extracts question from last message, checks question_cache for similar questions via embedding similarity
  3. Cache hit - Creates cached_answer_state, streams cached answer via cacheStreamingLLM
  4. Cache miss - Calls handleGlowChatCore:
    • Loads glowSettings by glowCurrentSlug
    • Builds system prompt from flow description + Mermaid chart + current node instructions
    • Resolves tools for current node from nodesMetadata
    • Calls streamText with AI SDK (OpenAI GPT-4.1 by default)
    • On each step: prepareStep / onStepFinish handle tool calls, moveToNodeId, changeChatContext, etc.
  5. Stream response - Server streams tokens back; client renders via useChat / GlowChatMessageQueue

Key Features

moveToNodeId

A special tool that updates currentNodeId when the flow transitions to a new node. The AI must call it before following the new node's instructions so that the correct tools are available.

changeChatContext / returnToContext

Tools that switch the chat to a different flow (different glowCurrentSlug). Used for cross-flow navigation (e.g., "Go to support").

Response Caching

When enableCache is true, the system:

  • Extracts the user's question from the last message
  • Generates an embedding and searches question_cache for similar questions
  • On match (above similarity threshold), streams the cached answer instead of calling the LLM
  • Saves token usage and improves latency for repeated questions

Mock LLM

For testing, mockStateId can be set on a chat to use @zooly/llm-mock instead of the real model, enabling deterministic or scripted responses.

Related Documentation