# tambo-ai/tambo architecture

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

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

## Overview

##### Project Type and Purpose
- This is a monorepo developer toolkit (“tambo-ai”) centered around a React SDK for generative UI components, plus supporting packages and a demo.
- Top‐level modules:
– cli: a CLI tool to scaffold, add, update, and manage tambo-based apps
– create-tambo-app: a thin wrapper around the CLI for “npm create tambo-app”
– packages/*: shared ESLint and TypeScript config packages
– react-sdk: the core React library providing TamboProvider, hooks, registry, and MCP clients
– showcase: a Next.js demonstration app consuming react-sdk

##### File Structure Analysis
– Monorepo orchestrated by turbo.json and workspaces (package.json)
– cli/src/commands: command modules (create-app, add, upgrade, etc.)
– cli/src/registry: built‐in component registry templates & JSON configs
– react-sdk/src:
- providers: TamboProvider, MCP provider, registry provider
- hooks: useTamboThreadInput, useTamboComponentState, etc.
- mcp: MCP‐client implementations
- util/model: component metadata, schemas, thread data
– showcase/src: Next.js app organized by route, UI primitives, and imports from react-sdk

##### Key README Insights
– tambo-ai exposes a client‐side registry of React components to an LLM via “MCP” servers
– You register your components with name, description, Zod schema; wrap app in TamboProvider; use hooks to submit messages and render AI‐generated components
– Supports pluggable “tools” and custom MCP servers, relying on streaming API

##### Main Components
A. Monorepo Orchestrator
- Turbo (turbo.json), GitHub workflows (CI, release)
B. CLI Layer (cli & create-tambo-app)
- Commands: create-app, add, init, list, upgrade
- Templates & registry JSON → scaffolding
C. Config Packages
- ESLint and TypeScript configs used by CLI, SDK, and showcase
D. Core Library (react-sdk)
- TamboProvider & TamboMcpProvider (React Context)
- Registry Provider (component registry)
- Hooks (input, streaming, component state)
- MCP clients (HTTP transport)
- Models & Zod schemas
E. Demo Application (showcase)
- Next.js front-end consuming react-sdk
- Components folders organized by feature (message-primitives, generative, canvas, etc.)
F. External Services
- MCP Servers (user‐configured endpoints)
- LLM API backends (OpenAI, Azure, etc.)

##### Relationships & Data Flows
- Developer → [CLI] → scaffolds new app code (using templates from cli/src/registry)
- Generated App → installs react-sdk and config packages → developer code
- Runtime: User input in UI → useTamboThreadInput.submit() → TamboMcpProvider → MCP Server → LLM → stream responses back → react-sdk updates component state → UI renders new components
- Tools: optional functions registered in TamboProvider that LLM can invoke via MCP

##### Architectural Patterns & Design Principles
- Monorepo (turbo) for unified builds, testing, and release
- CLI scaffolding pattern with pluggable commands and JSON‐based templates
- React Context + hooks pattern for state management and streaming data
- Registry pattern: decouple component metadata & rendering logic
- Pluggable transport/providers for MCP servers and tools
- Zod schemas for prop/tool validation and type safety

##### Essential Elements to Capture
– Monorepo root and CI/CD orchestration
– CLI and create-tambo-app packages with template registry
– Shared config packages (eslint-config, typescript-config)
– react-sdk internals: providers, hooks, mcp clients, registry, models
– Demo application structure and its import of react-sdk
– External MCP servers and LLM API endpoints
– Flow of user input → hook → network call → component state → rendered component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Orchestrator
    subgraph "Monorepo Orchestrator" 
        ORG_TURBO["turbo.json"]:::orchestrator
        ORG_CI[".github/workflows/ci.yml"]:::orchestrator
        ORG_RELEASE[".github/workflows/release-please.yml"]:::orchestrator
        ORG_WS["package.json (workspaces)"]:::orchestrator
    end

    %% Dev-time Flow
    subgraph "Dev-time"
        direction TB
        DEV_CLI["CLI Layer"]:::cli
        DEV_CREATE["Create-Tambo-App"]:::cli
        DEV_CONFIG["Shared Config Packages"]:::lib
    end

    %% Build Orchestration
    subgraph "Build"
        direction TB
        ORG_TURBO -->|"build/test"| CLI_PKG["cli"]:::cli
        ORG_TURBO -->|"build/test"| CTA_PKG["create-tambo-app"]:::cli
        ORG_TURBO -->|"build/test"| CFG_PKG["packages/*"]:::lib
        ORG_TURBO -->|"build/test"| SDK_PKG["react-sdk"]:::lib
        ORG_TURBO -->|"build/test"| SHOW_PKG["showcase"]:::demo
    end

    %% Runtime Flow
    subgraph "Runtime"
        direction TB
        SHOWCASE["Demo Application (showcase)"]:::demo
        SDK["react-sdk"]:::lib
        EXTSVC_MCP["MCP Servers"]:::external
        EXTSVC_LLM["LLM Providers"]:::external
    end

    %% Dev-time Relationships
    DEV_CLI -->|"templates & registry"| DEV_CREATE
    DEV_CLI -->|"uses configs"| DEV_CONFIG
    DEV_CREATE -->|"scaffolds app code"| SHOWCASE

    %% Runtime Relationships
    SHOWCASE -->|"imports"| SDK
    SHOWCASE -->|"ui input via hooks"| SDK
    SDK -->|"HTTP requests"| EXTSVC_MCP
    EXTSVC_MCP -->|"calls API"| EXTSVC_LLM
    EXTSVC_LLM -->|"stream response"| SDK
    SDK -->|"updates component state"| SHOWCASE

    %% Click Events - Monorepo Orchestrator
    click ORG_TURBO "https://github.com/tambo-ai/tambo/blob/main/turbo.json"
    click ORG_CI "https://github.com/tambo-ai/tambo/blob/main/.github/workflows/ci.yml"
    click ORG_RELEASE "https://github.com/tambo-ai/tambo/blob/main/.github/workflows/release-please.yml"
    click ORG_WS "https://github.com/tambo-ai/tambo/blob/main/package.json"

    %% Click Events - CLI Layer
    click DEV_CLI "https://github.com/tambo-ai/tambo/blob/main/cli/src/cli.ts"
    click DEV_CLI "https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/create-app.ts"
    click DEV_CLI "https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/add/index.ts"
    click DEV_CLI "https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/upgrade/index.ts"
    click DEV_CLI "https://github.com/tambo-ai/tambo/tree/main/cli/src/registry"
    click DEV_CLI "https://github.com/tambo-ai/tambo/blob/main/cli/src/templates/tambo-template.ts"

    %% Click Events - Create-Tambo-App
    click DEV_CREATE "https://github.com/tambo-ai/tambo/blob/main/create-tambo-app/src/index.ts"
    click DEV_CREATE "https://github.com/tambo-ai/tambo/blob/main/create-tambo-app/package.json"

    %% Click Events - Shared Config Packages
    click DEV_CONFIG "https://github.com/tambo-ai/tambo/blob/main/packages/eslint-config/base.mjs"
    click DEV_CONFIG "https://github.com/tambo-ai/tambo/blob/main/packages/eslint-config/next.mjs"
    click DEV_CONFIG "https://github.com/tambo-ai/tambo/blob/main/packages/eslint-config/react-internal.mjs"
    click DEV_CONFIG "https://github.com/tambo-ai/tambo/blob/main/packages/typescript-config/base.json"
    click DEV_CONFIG "https://github.com/tambo-ai/tambo/blob/main/packages/typescript-config/nextjs.json"
    click DEV_CONFIG "https://github.com/tambo-ai/tambo/blob/main/packages/typescript-config/react-library.json"

    %% Click Events - Core Library
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/providers/tambo-provider.tsx"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/providers/tambo-mcp-provider.tsx"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/providers/tambo-registry-provider.tsx"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/providers/tambo-component-provider.tsx"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/providers/tambo-thread-provider.tsx"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/hooks/use-thread-input.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/hooks/use-suggestions.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/hooks/use-component-state.tsx"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/hooks/use-streaming-props.tsx"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/hooks/index.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/mcp/mcp-client.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/mcp/tambo-mcp-provider.tsx"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/mcp/mcp-tools-client.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/model/component-metadata.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/model/generate-component-response.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/model/tambo-thread.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/model/validate-input.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/util/registry.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/util/generate-component.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/util/tool-caller.ts"
    click SDK "https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/util/validate-zod-schema.ts"

    %% Click Events - Showcase
    click SHOWCASE "https://github.com/tambo-ai/tambo/tree/main/showcase/src/app/"
    click SHOWCASE "https://github.com/tambo-ai/tambo/tree/main/showcase/src/app/components/"
    click SHOWCASE "https://github.com/tambo-ai/tambo/tree/main/showcase/src/components/ui/"
    click SHOWCASE "https://github.com/tambo-ai/tambo/blob/main/showcase/src/lib/thread-hooks.ts"
    click SHOWCASE "https://github.com/tambo-ai/tambo/tree/main/showcase/src/providers/"
    click SHOWCASE "https://github.com/tambo-ai/tambo/blob/main/showcase/next.config.ts"
    click SHOWCASE "https://github.com/tambo-ai/tambo/blob/main/showcase/package.json"

    %% Click Events - CI/CD & Release Orchestration
    click ORG_CI "https://github.com/tambo-ai/tambo/blob/main/.github/workflows/conventional-commits.yml"
    click ORG_CI "https://github.com/tambo-ai/tambo/blob/main/.github/workflows/claude.yml"
    click ORG_RELEASE "https://github.com/tambo-ai/tambo/blob/main/release-please-config.json"

    %% Styles
    classDef orchestrator fill:#F0F0F0,stroke:#666,stroke-width:1px
    classDef cli fill:#E0F2FF,stroke:#0B69A3,stroke-width:1px
    classDef lib fill:#E6F4EA,stroke:#27632A,stroke-width:1px
    classDef demo fill:#FFF4E5,stroke:#B35D00,stroke-width:1px
    classDef external fill:#FDECEA,stroke:#A61E4D,stroke-width:1px
```
