# mckaywrigley/chatbot-ui architecture

> Architecture diagram of the GitHub repository mckaywrigley/chatbot-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mckaywrigley/chatbot-ui
- Repository: https://github.com/mckaywrigley/chatbot-ui

## Overview

#### 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: [`components/chat/chat-hooks/use-chat-handler.tsx`](https://github.com/mckaywrigley/chatbot-ui/blob/main/components/chat/chat-hooks/use-chat-handler.tsx) (Chat state and submit), [`supabase/migrations/20240108234540_setup.sql`](https://github.com/mckaywrigley/chatbot-ui/blob/main/supabase/migrations/20240108234540_setup.sql) (Supabase backend), [`app/api/retrieval/retrieve/route.ts`](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/api/retrieval/retrieve/route.ts) (Retrieval query), [`lib/supabase/server.ts`](https://github.com/mckaywrigley/chatbot-ui/blob/main/lib/supabase/server.ts) (Supabase clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js UI"]
  node_middleware["Session middleware<br/>Next.js middleware<br/>[middleware.ts]"]
  node_app_shell["Locale app shell<br/>App Router layout<br/>[layout.tsx]"]
  node_workspace_shell["Workspace shell<br/>App Router layout<br/>[layout.tsx]"]
  node_chat_page["Workspace chat route<br/>App Router page<br/>[page.tsx]"]
  node_auth_callback["Auth callback<br/>API route<br/>[route.ts]"]
  node_setup["Setup onboarding<br/>App Router page<br/>[page.tsx]"]
end

subgraph group_chat["Chat and models"]
  node_chat_ui["Chat UI<br/>React component<br/>[chat-ui.tsx]"]
  node_chat_state["Chat state and submit<br/>React context and hook"]
  node_model_gateway{{"Provider chat gateway<br/>API routes<br/>[route.ts]"}}
  node_model_support["Model catalog and helpers<br/>Server model layer<br/>[llm-list.ts]"]
end

subgraph group_data["Workspace data"]
  node_workspace_db["Workspace data access<br/>Database layer<br/>[workspaces.ts]"]
  node_supabase[("Supabase backend<br/>Postgres, Auth, Storage")]
  node_supabase_clients["Supabase clients<br/>Browser and server clients<br/>[server.ts]"]
end

subgraph group_retrieval["Retrieval pipeline"]
  node_ingestion["Document processing<br/>Retrieval API and processors<br/>[route.ts]"]
  node_retrieval["Retrieval query<br/>Retrieval API<br/>[route.ts]"]
  node_collections["Collections<br/>Database layer<br/>[collections.ts]"]
  node_local_embeddings["Local embeddings<br/>Embedding generator"]
end

node_middleware -->|"guards requests"| node_app_shell
node_app_shell -->|"routes into workspace"| node_workspace_shell
node_workspace_shell -->|"hosts"| node_chat_page
node_chat_page -->|"renders"| node_chat_ui
node_chat_ui -->|"uses"| node_chat_state
node_chat_state -->|"streams chat requests"| node_model_gateway
node_model_gateway -->|"builds provider requests"| node_model_support
node_chat_state -->|"loads and persists chats"| node_workspace_db
node_workspace_db -->|"reads and writes tenant data"| node_supabase
node_auth_callback -->|"establishes session"| node_supabase_clients
node_setup -->|"configures user access"| node_supabase_clients
node_supabase_clients -->|"accesses"| node_supabase
node_chat_state -.->|"requests chat context"| node_retrieval
node_ingestion -.->|"generates embeddings"| node_local_embeddings
node_ingestion -->|"indexes into"| node_collections
node_collections -->|"persists metadata"| node_supabase
node_retrieval -->|"selects context from"| node_collections
node_retrieval -->|"queries stored content"| node_supabase

click node_middleware "https://github.com/mckaywrigley/chatbot-ui/blob/main/middleware.ts"
click node_app_shell "https://github.com/mckaywrigley/chatbot-ui/blob/main/app/%5Blocale%5D/layout.tsx"
click node_workspace_shell "https://github.com/mckaywrigley/chatbot-ui/blob/main/app/%5Blocale%5D/%5Bworkspaceid%5D/layout.tsx"
click node_chat_page "https://github.com/mckaywrigley/chatbot-ui/blob/main/app/%5Blocale%5D/%5Bworkspaceid%5D/chat/%5Bchatid%5D/page.tsx"
click node_auth_callback "https://github.com/mckaywrigley/chatbot-ui/blob/main/app/auth/callback/route.ts"
click node_setup "https://github.com/mckaywrigley/chatbot-ui/blob/main/app/%5Blocale%5D/setup/page.tsx"
click node_chat_ui "https://github.com/mckaywrigley/chatbot-ui/blob/main/components/chat/chat-ui.tsx"
click node_chat_state "https://github.com/mckaywrigley/chatbot-ui/blob/main/components/chat/chat-hooks/use-chat-handler.tsx"
click node_model_gateway "https://github.com/mckaywrigley/chatbot-ui/blob/main/app/api/chat/openai/route.ts"
click node_model_support "https://github.com/mckaywrigley/chatbot-ui/blob/main/lib/models/llm/llm-list.ts"
click node_workspace_db "https://github.com/mckaywrigley/chatbot-ui/blob/main/db/workspaces.ts"
click node_supabase "https://github.com/mckaywrigley/chatbot-ui/blob/main/supabase/migrations/20240108234540_setup.sql"
click node_supabase_clients "https://github.com/mckaywrigley/chatbot-ui/blob/main/lib/supabase/server.ts"
click node_ingestion "https://github.com/mckaywrigley/chatbot-ui/blob/main/app/api/retrieval/process/route.ts"
click node_retrieval "https://github.com/mckaywrigley/chatbot-ui/blob/main/app/api/retrieval/retrieve/route.ts"
click node_collections "https://github.com/mckaywrigley/chatbot-ui/blob/main/db/collections.ts"
click node_local_embeddings "https://github.com/mckaywrigley/chatbot-ui/blob/main/lib/generate-local-embedding.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_middleware,node_app_shell,node_workspace_shell,node_chat_page,node_auth_callback,node_setup toneBlue
class node_chat_ui,node_chat_state,node_model_gateway,node_model_support toneAmber
class node_workspace_db,node_supabase,node_supabase_clients toneMint
class node_ingestion,node_retrieval,node_collections,node_local_embeddings toneRose
```

## Components

### Next.js UI

- [Session middleware](https://github.com/mckaywrigley/chatbot-ui/blob/main/middleware.ts): Next.js middleware · Applies locale and session-aware access control. · `middleware.ts`
- [Locale app shell](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/%5Blocale%5D/layout.tsx): App Router layout · `app/[locale]/layout.tsx`
- [Workspace shell](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/%5Blocale%5D/%5Bworkspaceid%5D/layout.tsx): App Router layout · Scopes navigation and UI to a workspace. · `app/[locale]/[workspaceid]/layout.tsx`
- [Workspace chat route](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/%5Blocale%5D/%5Bworkspaceid%5D/chat/%5Bchatid%5D/page.tsx): App Router page · `app/[locale]/[workspaceid]/chat/[chatid]/page.tsx`
- [Auth callback](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/auth/callback/route.ts): API route · `app/auth/callback/route.ts`
- [Setup onboarding](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/%5Blocale%5D/setup/page.tsx): App Router page · `app/[locale]/setup/page.tsx`

### Chat and models

- [Chat UI](https://github.com/mckaywrigley/chatbot-ui/blob/main/components/chat/chat-ui.tsx): React component · `components/chat/chat-ui.tsx`
- [Chat state and submit](https://github.com/mckaywrigley/chatbot-ui/blob/main/components/chat/chat-hooks/use-chat-handler.tsx): React context and hook · Coordinates selections, history, submission, and streamed responses. · `components/chat/chat-hooks/use-chat-handler.tsx`
- [Provider chat gateway](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/api/chat/openai/route.ts): API routes · Server boundary for provider credentials, protocols, streaming, and tools. · `app/api/chat/openai/route.ts`
- [Model catalog and helpers](https://github.com/mckaywrigley/chatbot-ui/blob/main/lib/models/llm/llm-list.ts): Server model layer · `lib/models/llm/llm-list.ts`

### Workspace data

- [Workspace data access](https://github.com/mckaywrigley/chatbot-ui/blob/main/db/workspaces.ts): Database layer · Encapsulates workspace-scoped chats, messages, and related records. · `db/workspaces.ts`
- [Supabase backend](https://github.com/mckaywrigley/chatbot-ui/blob/main/supabase/migrations/20240108234540_setup.sql): Postgres, Auth, Storage · Durable tenant data, identity, policies, and file assets. · `supabase/migrations/20240108234540_setup.sql`
- [Supabase clients](https://github.com/mckaywrigley/chatbot-ui/blob/main/lib/supabase/server.ts): Browser and server clients · Separates browser sessions from server-side Supabase access. · `lib/supabase/server.ts`

### Retrieval pipeline

- [Document processing](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/api/retrieval/process/route.ts): Retrieval API and processors · Converts uploaded documents into retrieval-ready content. · `app/api/retrieval/process/route.ts`
- [Retrieval query](https://github.com/mckaywrigley/chatbot-ui/blob/main/app/api/retrieval/retrieve/route.ts): Retrieval API · Queries selected collection context during chat. · `app/api/retrieval/retrieve/route.ts`
- [Collections](https://github.com/mckaywrigley/chatbot-ui/blob/main/db/collections.ts): Database layer · Models retrieval selection and assistant/file links. · `db/collections.ts`
- [Local embeddings](https://github.com/mckaywrigley/chatbot-ui/blob/main/lib/generate-local-embedding.ts): Embedding generator · Optional local embedding generation. · `lib/generate-local-embedding.ts`

## Connections

- 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
