# tanstack/ai architecture

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

- Interactive diagram: https://gitdiagram.com/tanstack/ai
- Repository: https://github.com/tanstack/ai

## Overview

TanStack AI is a modular TypeScript SDK for building streaming, tool-using AI applications. Its principal workflow is an application request entering the core chat activity, using a provider adapter to communicate with a model, then streaming results to a client. Separate packages add framework bindings, media and realtime generation, agent execution, MCP tools, Code Mode, and observability. The README documents the product-level connections; sampled source adds details for lazy tool discovery and harness protocol/session handling, but many subsystem implementations were not sampled.

Main entry points: [`packages/ai/src/activities/chat`](https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat) (Chat activity), [`packages/ai-client/src`](https://github.com/tanstack/ai/tree/main/packages/ai-client/src) (Headless client), [`packages/ai/src/activities/chat/tools`](https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat/tools) (Tool definitions), [`packages/ai/src/activities/chat/agents`](https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat/agents) (Subagents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core AI runtime"]
  node_chat["Chat activity"]
  node_coretypes["Core contracts<br/>[types.ts]"]
end

subgraph group_providers["Model providers"]
  node_provider["Provider adapters"]
  node_anthropic["Anthropic adapter"]
  node_gemini["Gemini adapter"]
end

subgraph group_clients["Clients and media"]
  node_client["Headless client"]
  node_frameworks["Framework bindings"]
  node_generation["Media generation"]
  node_realtime["Realtime voice"]
  node_persistence[("Chat persistence")]
end

subgraph group_agents["Agents and tools"]
  node_tools["Tool definitions"]
  node_lazytools["Lazy discovery"]
  node_agents["Subagents"]
  node_codemode["Code Mode"]
  node_snippets["Code snippets"]
end

subgraph group_integrations["Runtime integrations"]
  node_mcp["MCP integration"]
  node_harness["Agent harness"]
  node_protocol["Harness protocol<br/>[protocol.ts]"]
  node_devtools["Devtools"]
end

node_app(("Application"))

node_app -->|"calls"| node_chat
node_chat -->|"uses adapter"| node_provider
node_chat -->|"uses adapter"| node_anthropic
node_chat -->|"uses adapter"| node_gemini
node_chat -.->|"uses contracts"| node_coretypes
node_chat -->|"attaches tools"| node_tools
node_chat -->|"discovers tools"| node_lazytools
node_chat -->|"routes agents"| node_agents
node_agents -.->|"can invoke"| node_codemode
node_codemode -->|"uses snippets"| node_snippets
node_tools -.->|"can use MCP"| node_mcp
node_client -->|"streams requests"| node_chat
node_frameworks -->|"binds client"| node_client
node_chat -->|"supports generation"| node_generation
node_client -.->|"persists state"| node_persistence
node_client -->|"supports realtime"| node_realtime
node_harness -->|"handles frames"| node_protocol
node_devtools -->|"observes activity"| node_chat

click node_chat "https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat"
click node_coretypes "https://github.com/tanstack/ai/blob/main/packages/ai/src/types.ts"
click node_provider "https://github.com/tanstack/ai/tree/main/packages/ai-openai/src"
click node_anthropic "https://github.com/tanstack/ai/tree/main/packages/ai-anthropic/src"
click node_gemini "https://github.com/tanstack/ai/tree/main/packages/ai-gemini/src"
click node_client "https://github.com/tanstack/ai/tree/main/packages/ai-client/src"
click node_frameworks "https://github.com/tanstack/ai/tree/main/packages/ai-react/src"
click node_generation "https://github.com/tanstack/ai/tree/main/packages/ai/src/activities"
click node_realtime "https://github.com/tanstack/ai/tree/main/packages/ai-gemini/src/realtime"
click node_tools "https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat/tools"
click node_lazytools "https://github.com/tanstack/ai/blob/main/packages/ai/src/activities/chat/tools/lazy-tool-manager.ts"
click node_agents "https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat/agents"
click node_codemode "https://github.com/tanstack/ai/tree/main/packages/ai-code-mode/src"
click node_snippets "https://github.com/tanstack/ai/tree/main/packages/ai-code-mode-snippets/src"
click node_mcp "https://github.com/tanstack/ai/tree/main/packages/ai-mcp/src"
click node_harness "https://github.com/tanstack/ai/tree/main/packages/ai-harness/src"
click node_protocol "https://github.com/tanstack/ai/blob/main/packages/ai-harness/src/protocol.ts"
click node_devtools "https://github.com/tanstack/ai/tree/main/packages/ai-devtools/src"
click node_persistence "https://github.com/tanstack/ai/blob/main/packages/ai-client/src/storage-adapters.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_coretypes toneBlue
class node_provider,node_anthropic,node_gemini toneAmber
class node_client,node_frameworks,node_generation,node_realtime,node_persistence toneMint
class node_tools,node_lazytools,node_agents,node_codemode,node_snippets toneRose
class node_mcp,node_harness,node_protocol,node_devtools,node_app toneIndigo
```

## Components

### Core AI runtime

- [Chat activity](https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat): `packages/ai/src/activities/chat`
- [Core contracts](https://github.com/tanstack/ai/blob/main/packages/ai/src/types.ts): `packages/ai/src/types.ts`

### Model providers

- [Provider adapters](https://github.com/tanstack/ai/tree/main/packages/ai-openai/src): `packages/ai-openai/src`
- [Anthropic adapter](https://github.com/tanstack/ai/tree/main/packages/ai-anthropic/src): `packages/ai-anthropic/src`
- [Gemini adapter](https://github.com/tanstack/ai/tree/main/packages/ai-gemini/src): `packages/ai-gemini/src`

### Clients and media

- [Headless client](https://github.com/tanstack/ai/tree/main/packages/ai-client/src): `packages/ai-client/src`
- [Framework bindings](https://github.com/tanstack/ai/tree/main/packages/ai-react/src): `packages/ai-react/src`
- [Media generation](https://github.com/tanstack/ai/tree/main/packages/ai/src/activities): `packages/ai/src/activities`
- [Realtime voice](https://github.com/tanstack/ai/tree/main/packages/ai-gemini/src/realtime): `packages/ai-gemini/src/realtime`
- [Chat persistence](https://github.com/tanstack/ai/blob/main/packages/ai-client/src/storage-adapters.ts): `packages/ai-client/src/storage-adapters.ts`

### Agents and tools

- [Tool definitions](https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat/tools): `packages/ai/src/activities/chat/tools`
- [Lazy discovery](https://github.com/tanstack/ai/blob/main/packages/ai/src/activities/chat/tools/lazy-tool-manager.ts): `packages/ai/src/activities/chat/tools/lazy-tool-manager.ts`
- [Subagents](https://github.com/tanstack/ai/tree/main/packages/ai/src/activities/chat/agents): `packages/ai/src/activities/chat/agents`
- [Code Mode](https://github.com/tanstack/ai/tree/main/packages/ai-code-mode/src): `packages/ai-code-mode/src`
- [Code snippets](https://github.com/tanstack/ai/tree/main/packages/ai-code-mode-snippets/src): `packages/ai-code-mode-snippets/src`

### Runtime integrations

- [MCP integration](https://github.com/tanstack/ai/tree/main/packages/ai-mcp/src): `packages/ai-mcp/src`
- [Agent harness](https://github.com/tanstack/ai/tree/main/packages/ai-harness/src): `packages/ai-harness/src`
- [Harness protocol](https://github.com/tanstack/ai/blob/main/packages/ai-harness/src/protocol.ts): `packages/ai-harness/src/protocol.ts`
- [Devtools](https://github.com/tanstack/ai/tree/main/packages/ai-devtools/src): `packages/ai-devtools/src`

### Other components

- **Application**

## Connections

- Application → Chat activity: calls (evidence: `README.md`)
- Chat activity → Provider adapters: uses adapter (evidence: `README.md`)
- Chat activity → Anthropic adapter: uses adapter (evidence: `README.md`)
- Chat activity → Gemini adapter: uses adapter (evidence: `README.md`)
- Chat activity → Core contracts: uses contracts (evidence: `packages/ai/src/activities/chat/tools/lazy-tool-manager.ts`)
- Chat activity → Tool definitions: attaches tools (evidence: `README.md`)
- Chat activity → Lazy discovery: discovers tools (evidence: `packages/ai/src/activities/chat/tools/lazy-tool-manager.ts`)
- Chat activity → Subagents: routes agents (evidence: `packages/ai/src/activities/chat/agents/route.ts`)
- Subagents → Code Mode: can invoke
- Code Mode → Code snippets: uses snippets (evidence: `README.md`)
- Tool definitions → MCP integration: can use MCP
- Headless client → Chat activity: streams requests (evidence: `README.md`)
- Framework bindings → Headless client: binds client (evidence: `README.md`)
- Chat activity → Media generation: supports generation (evidence: `README.md`)
- Headless client → Chat persistence: persists state (evidence: `packages/ai-client/src/storage-adapters.ts`)
- Headless client → Realtime voice: supports realtime (evidence: `README.md`)
- Agent harness → Harness protocol: handles frames (evidence: `packages/ai-harness/src/protocol.ts`)
- Devtools → Chat activity: observes activity (evidence: `README.md`)