How mckaywrigley/chatbot-ui works
Purpose and runtime
Chatbot UI is a multi-user, workspace-scoped AI chat application. It runs as a Next.js App Router application (Node.js 18-compatible) and can deploy to Vercel. Its primary backend is Supabase: Postgres, Auth, Storage, and likely database-side retrieval support. Local Supabase requires Docker; Ollama is optional for local models.
Application entry and routing
Locale-prefixed routes establish the UI shell, authentication/setup flow, help, and workspace-specific chat navigation. The central interactive route is a workspace chat, optionally addressed by chat ID.
• app/[locale]/layout.tsx
• app/[locale]/[workspaceid]/layout.tsx
• app/[locale]/[workspaceid]/chat/[chatid]/page.tsx
• middleware.ts
Client state and chat orchestration
The chat UI composes input, settings, selected models/assistants/tools/files, message rendering, and streaming response consumption. React context provides shared application state; specialized hooks coordinate chat submission, history, prompts/commands, scrolling, and file selection.
• context/context.tsx
• components/chat/chat-ui.tsx
• components/chat/chat-hooks/use-chat-handler.tsx
• components/messages/message.tsx
Multi-provider model gateway
Server route handlers expose a provider-specific boundary for chat completions, isolating credentials and provider protocol differences from the browser. Supported targets include OpenAI, Anthropic, Azure OpenAI, Google, Groq, Mistral, OpenRouter, Perplexity, custom endpoints, and tool execution; assistant-specific OpenAI access is separate. Model catalogs and server helpers support request construction and streaming.
• app/api/chat/openai/route.ts
• app/api/chat/anthropic/route.ts
• app/api/chat/tools/route.ts
• lib/server/server-chat-helpers.ts
• lib/models/llm/llm-list.ts
Persistence, tenancy, and storage
A workspace is the principal organizational boundary for chats, messages, assistants, prompts, models, files, folders, collections, and tools. The db/ layer encapsulates application data operations, while Supabase migrations define the durable schema and associated policies. Supabase Storage holds user/profile, workspace, assistant, message, and general file assets.
• db/workspaces.ts
• db/chats.ts
• db/messages.ts
• db/storage/files.ts
• supabase/migrations/20240108234540_setup.sql
Retrieval and document ingestion
Uploaded documents can be processed into retrieval-ready content through API routes and format-specific processors, then queried during chat. Collections and assistant-to-file/collection links model the selection boundary for retrieval context; embedding generation can run locally.
• app/api/retrieval/process/route.ts
• app/api/retrieval/retrieve/route.ts
• lib/retrieval/processing/index.ts
• lib/generate-local-embedding.ts
• db/collections.ts
Auth, onboarding, and operational boundaries
Supabase Auth callback handling gates access; setup and login routes support initial user configuration. Browser/server Supabase clients and middleware separate session-aware UI access from privileged server operations. Environment configuration supplies Supabase credentials and provider keys; service-role access is explicitly required for storage cleanup/migration setup.
• app/auth/callback/route.ts
• app/[locale]/setup/page.tsx
• lib/supabase/browser-client.ts
• lib/supabase/server.ts
• .env.local.example
Main entry points: use-chat-handler.tsx Chat state and submit · 20240108234540_setup.sql Supabase backend · route.ts Retrieval query · server.ts Supabase clients
Components 17
Next.js UI
- Session middleware · Applies locale and session-aware access control.
middleware.ts - Locale app shell
app/[locale]/layout.tsx - Workspace shell · Scopes navigation and UI to a workspace.
app/[locale]/[workspaceid]/layout.tsx - Workspace chat route
app/[locale]/[workspaceid]/chat/[chatid]/page.tsx - Auth callback
app/auth/callback/route.ts - Setup onboarding
app/[locale]/setup/page.tsx
Chat and models
- Chat UI
components/chat/chat-ui.tsx - Chat state and submit · Coordinates selections, history, submission, and streamed responses.
components/chat/chat-hooks/use-chat-handler.tsx - Provider chat gateway · Server boundary for provider credentials, protocols, streaming, and tools.
app/api/chat/openai/route.ts - Model catalog and helpers
lib/models/llm/llm-list.ts
Workspace data
- Workspace data access · Encapsulates workspace-scoped chats, messages, and related records.
db/workspaces.ts - Supabase backend · Durable tenant data, identity, policies, and file assets.
supabase/migrations/20240108234540_setup.sql - Supabase clients · Separates browser sessions from server-side Supabase access.
lib/supabase/server.ts
Retrieval pipeline
- Document processing · Converts uploaded documents into retrieval-ready content.
app/api/retrieval/process/route.ts - Retrieval query · Queries selected collection context during chat.
app/api/retrieval/retrieve/route.ts - Collections · Models retrieval selection and assistant/file links.
db/collections.ts - Local embeddings · Optional local embedding generation.
lib/generate-local-embedding.ts
Connections 18
- Session middleware → Locale app shell: guards requests
- Locale app shell → Workspace shell: routes into workspace
- Workspace shell → Workspace chat route: hosts
- Workspace chat route → Chat UI: renders
- Chat UI → Chat state and submit: uses
- Chat state and submit → Provider chat gateway: streams chat requests
- Provider chat gateway → Model catalog and helpers: builds provider requests
- Chat state and submit → Workspace data access: loads and persists chats
- Workspace data access → Supabase backend: reads and writes tenant data
- Auth callback → Supabase clients: establishes session
- Setup onboarding → Supabase clients: configures user access
- Supabase clients → Supabase backend: accesses
- Chat state and submit → Retrieval query: requests chat context
- Document processing → Local embeddings: generates embeddings
- Document processing → Collections: indexes into
- Collections → Supabase backend: persists metadata
- Retrieval query → Collections: selects context from
- Retrieval query → Supabase backend: queries stored content