# vercel/chat architecture

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

- Interactive diagram: https://gitdiagram.com/vercel/chat
- Repository: https://github.com/vercel/chat

## Overview

Chat SDK is a TypeScript toolkit for writing chat bots once and connecting them to multiple messaging platforms. The principal runtime path is a platform event entering an adapter, reaching the bot’s Chat handlers, and producing a reply through an adapter; configured state is a separate persistence capability. Platform adapters also implement platform-specific cards and formatting. The README documents the CLI scaffold and adapter catalog as additional product capabilities. Relationships for unsampled subsystems are limited to documented links and source-index references.

Main entry points: [`packages/chat/src/chat.ts`](https://github.com/vercel/chat/blob/main/packages/chat/src/chat.ts) (Chat runtime), [`packages/create-chat-sdk/src/cli/program.ts`](https://github.com/vercel/chat/blob/main/packages/create-chat-sdk/src/cli/program.ts) (Project scaffolder), [`packages/adapter-discord/src/cards.ts`](https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/cards.ts) (Discord cards), [`packages/adapter-gchat/src/workspace-events.ts`](https://github.com/vercel/chat/blob/main/packages/adapter-gchat/src/workspace-events.ts) (Workspace events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_chat["Chat runtime<br/>[chat.ts]"]
  node_handlers["Event handlers<br/>[context.ts]"]
  node_history["History and prompts<br/>[index.ts]"]
  node_ai["AI tools and streaming<br/>[index.ts]"]
  node_workflow["Workflow approvals<br/>[index.ts]"]
end

subgraph group_platforms["Platform Adapters"]
  node_discord_cards["Discord cards<br/>[cards.ts]"]
  node_discord_markdown["Discord formatting<br/>[markdown.ts]"]
  node_gchat_cards["Google Chat cards<br/>[cards.ts]"]
  node_gchat_user["Google Chat users<br/>[user-info.ts]"]
  node_gchat_events["Workspace events"]
  node_github_cards["GitHub cards<br/>[cards.ts]"]
  node_messenger_cards["Messenger cards<br/>[cards.ts]"]
  node_teams_api["Teams API client<br/>[client.ts]"]
  node_telegram_markdown["Telegram formatting<br/>[markdown.ts]"]
  node_telegram_rich["Telegram rich text<br/>[rich.ts]"]
  node_telegram_split["Telegram splitting<br/>[split.ts]"]
  node_twilio_content["Twilio content<br/>[content.ts]"]
  node_twilio_cards["Twilio cards<br/>[cards.ts]"]
  node_whatsapp_cards["WhatsApp cards<br/>[cards.ts]"]
  node_whatsapp_markdown["WhatsApp formatting<br/>[markdown.ts]"]
end

subgraph group_catalog["Catalog and Setup"]
  node_adapter_catalog["Adapter catalog<br/>[index.ts]"]
  node_cli["Project scaffolder<br/>[program.ts]"]
  node_cli_agent["Agent detection<br/>[agent.ts]"]
end

subgraph group_state["State Backends"]
  node_memory_state[("Memory state<br/>[index.ts]")]
  node_redis_state[("Redis state<br/>[index.ts]")]
  node_pg_state[("Postgres state<br/>[index.ts]")]
  node_ioredis_state[("ioredis state<br/>[index.ts]")]
end

node_developer(("Bot developer"))
node_platforms_ext(("Chat platforms"))

node_developer -->|"configures bot"| node_chat
node_platforms_ext -.->|"sends events"| node_chat
node_chat -.->|"dispatches events"| node_handlers
node_chat -.->|"sends replies"| node_platforms_ext
node_chat -->|"uses state"| node_memory_state
node_chat -->|"uses state"| node_redis_state
node_chat -.->|"uses state"| node_pg_state
node_chat -.->|"uses state"| node_ioredis_state
node_developer -->|"runs scaffold"| node_cli
node_cli -->|"reads options"| node_adapter_catalog
node_cli -->|"detects agent"| node_cli_agent
node_cli -->|"generates bot config"| node_chat
node_chat -.->|"provides AI APIs"| node_ai
node_chat -.->|"provides history"| node_history
node_chat -.->|"provides approvals"| node_workflow
node_discord_cards -.->|"formats cards"| node_discord_markdown
node_gchat_events -.->|"resolves users"| node_gchat_user
node_teams_api -.->|"calls Teams API"| node_platforms_ext
node_twilio_content -.->|"calls Twilio API"| node_platforms_ext

click node_chat "https://github.com/vercel/chat/blob/main/packages/chat/src/chat.ts"
click node_handlers "https://github.com/vercel/chat/blob/main/packages/chat/src/context.ts"
click node_history "https://github.com/vercel/chat/blob/main/packages/chat/src/history/index.ts"
click node_ai "https://github.com/vercel/chat/blob/main/packages/chat/src/ai/index.ts"
click node_workflow "https://github.com/vercel/chat/blob/main/packages/chat/src/workflow/index.ts"
click node_discord_cards "https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/cards.ts"
click node_discord_markdown "https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/markdown.ts"
click node_gchat_cards "https://github.com/vercel/chat/blob/main/packages/adapter-gchat/src/cards.ts"
click node_gchat_user "https://github.com/vercel/chat/blob/main/packages/adapter-gchat/src/user-info.ts"
click node_gchat_events "https://github.com/vercel/chat/blob/main/packages/adapter-gchat/src/workspace-events.ts"
click node_github_cards "https://github.com/vercel/chat/blob/main/packages/adapter-github/src/cards.ts"
click node_messenger_cards "https://github.com/vercel/chat/blob/main/packages/adapter-messenger/src/cards.ts"
click node_teams_api "https://github.com/vercel/chat/blob/main/packages/adapter-teams/src/api/client.ts"
click node_telegram_markdown "https://github.com/vercel/chat/blob/main/packages/adapter-telegram/src/markdown.ts"
click node_telegram_rich "https://github.com/vercel/chat/blob/main/packages/adapter-telegram/src/rich.ts"
click node_telegram_split "https://github.com/vercel/chat/blob/main/packages/adapter-telegram/src/split.ts"
click node_twilio_content "https://github.com/vercel/chat/blob/main/packages/adapter-twilio/src/api/content.ts"
click node_twilio_cards "https://github.com/vercel/chat/blob/main/packages/adapter-twilio/src/cards.ts"
click node_whatsapp_cards "https://github.com/vercel/chat/blob/main/packages/adapter-whatsapp/src/cards.ts"
click node_whatsapp_markdown "https://github.com/vercel/chat/blob/main/packages/adapter-whatsapp/src/markdown.ts"
click node_adapter_catalog "https://github.com/vercel/chat/blob/main/packages/catalog/src/index.ts"
click node_cli "https://github.com/vercel/chat/blob/main/packages/create-chat-sdk/src/cli/program.ts"
click node_cli_agent "https://github.com/vercel/chat/blob/main/packages/create-chat-sdk/src/cli/agent.ts"
click node_memory_state "https://github.com/vercel/chat/blob/main/packages/state-memory/src/index.ts"
click node_redis_state "https://github.com/vercel/chat/blob/main/packages/state-redis/src/index.ts"
click node_pg_state "https://github.com/vercel/chat/blob/main/packages/state-pg/src/index.ts"
click node_ioredis_state "https://github.com/vercel/chat/blob/main/packages/state-ioredis/src/index.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_chat,node_handlers,node_history,node_ai,node_workflow toneBlue
class node_discord_cards,node_discord_markdown,node_gchat_cards,node_gchat_user,node_gchat_events,node_github_cards,node_messenger_cards,node_teams_api,node_telegram_markdown,node_telegram_rich,node_telegram_split,node_twilio_content,node_twilio_cards,node_whatsapp_cards,node_whatsapp_markdown toneAmber
class node_adapter_catalog,node_cli,node_cli_agent toneMint
class node_memory_state,node_redis_state,node_pg_state,node_ioredis_state toneRose
class node_developer,node_platforms_ext toneIndigo
```

## Components

### Bot Runtime

- [Chat runtime](https://github.com/vercel/chat/blob/main/packages/chat/src/chat.ts): `packages/chat/src/chat.ts`
- [Event handlers](https://github.com/vercel/chat/blob/main/packages/chat/src/context.ts): `packages/chat/src/context.ts`
- [History and prompts](https://github.com/vercel/chat/blob/main/packages/chat/src/history/index.ts): `packages/chat/src/history/index.ts`
- [AI tools and streaming](https://github.com/vercel/chat/blob/main/packages/chat/src/ai/index.ts): `packages/chat/src/ai/index.ts`
- [Workflow approvals](https://github.com/vercel/chat/blob/main/packages/chat/src/workflow/index.ts): `packages/chat/src/workflow/index.ts`

### Platform Adapters

- [Discord cards](https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/cards.ts): `packages/adapter-discord/src/cards.ts`
- [Discord formatting](https://github.com/vercel/chat/blob/main/packages/adapter-discord/src/markdown.ts): `packages/adapter-discord/src/markdown.ts`
- [Google Chat cards](https://github.com/vercel/chat/blob/main/packages/adapter-gchat/src/cards.ts): `packages/adapter-gchat/src/cards.ts`
- [Google Chat users](https://github.com/vercel/chat/blob/main/packages/adapter-gchat/src/user-info.ts): `packages/adapter-gchat/src/user-info.ts`
- [Workspace events](https://github.com/vercel/chat/blob/main/packages/adapter-gchat/src/workspace-events.ts): `packages/adapter-gchat/src/workspace-events.ts`
- [GitHub cards](https://github.com/vercel/chat/blob/main/packages/adapter-github/src/cards.ts): `packages/adapter-github/src/cards.ts`
- [Messenger cards](https://github.com/vercel/chat/blob/main/packages/adapter-messenger/src/cards.ts): `packages/adapter-messenger/src/cards.ts`
- [Teams API client](https://github.com/vercel/chat/blob/main/packages/adapter-teams/src/api/client.ts): `packages/adapter-teams/src/api/client.ts`
- [Telegram formatting](https://github.com/vercel/chat/blob/main/packages/adapter-telegram/src/markdown.ts): `packages/adapter-telegram/src/markdown.ts`
- [Telegram rich text](https://github.com/vercel/chat/blob/main/packages/adapter-telegram/src/rich.ts): `packages/adapter-telegram/src/rich.ts`
- [Telegram splitting](https://github.com/vercel/chat/blob/main/packages/adapter-telegram/src/split.ts): `packages/adapter-telegram/src/split.ts`
- [Twilio content](https://github.com/vercel/chat/blob/main/packages/adapter-twilio/src/api/content.ts): `packages/adapter-twilio/src/api/content.ts`
- [Twilio cards](https://github.com/vercel/chat/blob/main/packages/adapter-twilio/src/cards.ts): `packages/adapter-twilio/src/cards.ts`
- [WhatsApp cards](https://github.com/vercel/chat/blob/main/packages/adapter-whatsapp/src/cards.ts): `packages/adapter-whatsapp/src/cards.ts`
- [WhatsApp formatting](https://github.com/vercel/chat/blob/main/packages/adapter-whatsapp/src/markdown.ts): `packages/adapter-whatsapp/src/markdown.ts`

### Catalog and Setup

- [Adapter catalog](https://github.com/vercel/chat/blob/main/packages/catalog/src/index.ts): `packages/catalog/src/index.ts`
- [Project scaffolder](https://github.com/vercel/chat/blob/main/packages/create-chat-sdk/src/cli/program.ts): `packages/create-chat-sdk/src/cli/program.ts`
- [Agent detection](https://github.com/vercel/chat/blob/main/packages/create-chat-sdk/src/cli/agent.ts): `packages/create-chat-sdk/src/cli/agent.ts`

### State Backends

- [Memory state](https://github.com/vercel/chat/blob/main/packages/state-memory/src/index.ts): `packages/state-memory/src/index.ts`
- [Redis state](https://github.com/vercel/chat/blob/main/packages/state-redis/src/index.ts): `packages/state-redis/src/index.ts`
- [Postgres state](https://github.com/vercel/chat/blob/main/packages/state-pg/src/index.ts): `packages/state-pg/src/index.ts`
- [ioredis state](https://github.com/vercel/chat/blob/main/packages/state-ioredis/src/index.ts): `packages/state-ioredis/src/index.ts`

### Other components

- **Bot developer**
- **Chat platforms**

## Connections

- Bot developer → Chat runtime: configures bot
- Chat platforms → Chat runtime: sends events
- Chat runtime → Event handlers: dispatches events
- Chat runtime → Chat platforms: sends replies
- Chat runtime → Memory state: uses state
- Chat runtime → Redis state: uses state
- Chat runtime → Postgres state: uses state
- Chat runtime → ioredis state: uses state
- Bot developer → Project scaffolder: runs scaffold
- Project scaffolder → Adapter catalog: reads options
- Project scaffolder → Agent detection: detects agent (evidence: `packages/create-chat-sdk/src/cli/program.ts`)
- Project scaffolder → Chat runtime: generates bot config
- Chat runtime → AI tools and streaming: provides AI APIs
- Chat runtime → History and prompts: provides history
- Chat runtime → Workflow approvals: provides approvals
- Discord cards → Discord formatting: formats cards
- Workspace events → Google Chat users: resolves users
- Teams API client → Chat platforms: calls Teams API
- Twilio content → Chat platforms: calls Twilio API
