# Tambo AI Monorepo Structure: How Packages Are Organized in the Turborepo

> Discover the Tambo AI monorepo structure organized with Turborepo. Learn how React SDK, CLI, cloud platform, and utilities are separated into packages and apps.

- Repository: [tambo ai/tambo](https://github.com/tambo-ai/tambo)
- Tags: internals
- Published: 2026-02-16

---

**The Tambo AI monorepo uses a Turborepo architecture to separate the React SDK, CLI tooling, cloud platform, and shared utilities into distinct workspaces under `packages/` and `apps/` directories.**

The `tambo-ai/tambo` repository organizes its codebase as a modular monorepo that enables parallel development of the React SDK, command-line interface, documentation site, and hosted cloud services. This **Tambo AI monorepo structure** ensures that shared logic remains centralized while allowing each workspace to maintain independent release cycles and dependencies.

## Core Directory Layout in the Tambo AI Monorepo

The repository root contains eight primary directories that separate concerns between publishable SDKs, internal applications, and shared infrastructure.

### SDK and Developer Tools

The top-level folders for client-facing tools include:

- **`react-sdk/`** – Contains the main React SDK (`@tambo-ai/react`) with core hooks, providers, and UI utilities. Entry point: [[`react-sdk/src/index.ts`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts)](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts).
- **`cli/`** – Houses the command-line interface for project scaffolding and component generation. Key registry files live in [`cli/src/registry/`](https://github.com/tambo-ai/tambo/tree/main/cli/src/registry).
- **`create-tambo-app/`** – A project bootstrapper that generates new Tambo applications from templates.
- **`showcase/`** – A Next.js demo application that renders every SDK component and serves as a live documentation playground.
- **`docs/`** – The documentation site (`@tambo-ai/docs`) built with Fumadocs, containing guides and API references.

### Cloud Platform Applications

The **`apps/`** directory contains the hosted Tambo Cloud platform:

- **`apps/web/`** – The Next.js frontend for the cloud platform. Top-level layout: [[`apps/web/src/pages/_app.tsx`](https://github.com/tambo-ai/tambo/blob/main/apps/web/src/pages/_app.tsx)](https://github.com/tambo-ai/tambo/blob/main/apps/web/src/pages/_app.tsx).
- **`apps/api/`** – The NestJS API server handling backend logic. Entry module: [[`apps/api/src/app.module.ts`](https://github.com/tambo-ai/tambo/blob/main/apps/api/src/app.module.ts)](https://github.com/tambo-ai/tambo/blob/main/apps/api/src/app.module.ts).

### Shared Internal Packages

The **`packages/`** directory contains libraries shared across workspaces:

- **`packages/core/`** – Pure utilities for validation, cryptography, and threading. Exports: [[`packages/core/src/index.ts`](https://github.com/tambo-ai/tambo/blob/main/packages/core/src/index.ts)](https://github.com/tambo-ai/tambo/blob/main/packages/core/src/index.ts).
- **`packages/backend/`** – LLM and agent-side helpers with streaming utilities.
- **`packages/db/`** – Drizzle ORM schema, migrations, and database helpers. Schema definition: [[`packages/db/src/schema.ts`](https://github.com/tambo-ai/tambo/blob/main/packages/db/src/schema.ts)](https://github.com/tambo-ai/tambo/blob/main/packages/db/src/schema.ts).
- **`packages/eslint-config/`**, **`packages/typescript-config/`**, **`packages/vite-config/`** – Shared tooling configurations ensuring consistent linting and build setups. Base ESLint rules: [`packages/eslint-config/base.mjs`](https://github.com/tambo-ai/tambo/blob/main/packages/eslint-config/base.mjs).

## How Packages Relate and Share Code

The **Tambo AI monorepo structure** enforces relationships through workspace-level imports and shared configuration files.

### Workspace-Level Imports

Packages under `packages/` expose exports via workspace `"*"` versioning. This allows other workspaces to import them using scoped names like `@tambo-ai/core` or `@tambo-ai/db` without publishing to npm during development.

### Shared Configuration

ESLint, Prettier, TypeScript, and Vite configurations live in dedicated `packages/*-config` directories. Each package references these from its own [`tsconfig.json`](https://github.com/tambo-ai/tambo/blob/main/tsconfig.json) or [`vite.config.ts`](https://github.com/tambo-ai/tambo/blob/main/vite.config.ts), guaranteeing uniform developer experience across the repository.

### Component Synchronization

The CLI maintains a component registry in `cli/src/registry/`. During the build process, these components are automatically copied into `showcase/src/components/tambo/` and `docs/src/components/`. This single-source-of-truth model ensures that UI examples remain synchronized across the demo site and documentation.

### Cloud and SDK Parity

The cloud platform (`apps/web` and `apps/api`) consumes the same core utilities (`packages/core`) and database schema (`packages/db`) that the React SDK relies on. This shared foundation allows feature parity between the hosted product and the open-source SDK.

## Typical Development Workflow

Developers interact with the **Tambo AI monorepo structure** through specific workspace commands and cross-package dependencies.

1. **Add a new UI component** – Edit the definition in `cli/src/registry/`, then run the CLI generation script. The component automatically appears in both `showcase` and `docs`.

2. **Create a new backend service** – Place reusable logic in `packages/backend`, then import it from the NestJS services in `apps/api/src/`.

3. **Extend the SDK** – Add a hook or provider inside `react-sdk/src/`, then expose it via the package entry point at [`react-sdk/src/index.ts`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts).

4. **Run targeted development servers** – Use `npm run dev:sdk` to start the SDK watch mode alongside the showcase, or `npm run dev:cloud` to launch the cloud UI and API together.

## Key Source Files and Entry Points

Understanding the **Tambo AI monorepo structure** requires familiarity with these critical files:

| File | Role |
|------|------|
| [[`packages/core/src/index.ts`](https://github.com/tambo-ai/tambo/blob/main/packages/core/src/index.ts)](https://github.com/tambo-ai/tambo/blob/main/packages/core/src/index.ts) | Core pure utilities entry point |
| [[`packages/db/src/schema.ts`](https://github.com/tambo-ai/tambo/blob/main/packages/db/src/schema.ts)](https://github.com/tambo-ai/tambo/blob/main/packages/db/src/schema.ts) | Drizzle ORM schema definitions |
| [[`react-sdk/src/index.ts`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts)](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts) | React SDK public exports |
| [`cli/src/registry/`](https://github.com/tambo-ai/tambo/tree/main/cli/src/registry) | Component registry source files |
| [[`apps/api/src/app.module.ts`](https://github.com/tambo-ai/tambo/blob/main/apps/api/src/app.module.ts)](https://github.com/tambo-ai/tambo/blob/main/apps/api/src/app.module.ts) | NestJS API application root module |
| [[`apps/web/src/pages/_app.tsx`](https://github.com/tambo-ai/tambo/blob/main/apps/web/src/pages/_app.tsx)](https://github.com/tambo-ai/tambo/blob/main/apps/web/src/pages/_app.tsx) | Cloud platform Next.js application wrapper |
| [`packages/eslint-config/base.mjs`](https://github.com/tambo-ai/tambo/blob/main/packages/eslint-config/base.mjs) | Shared ESLint configuration base |
| [[`AGENTS.md`](https://github.com/tambo-ai/tambo/blob/main/AGENTS.md)](https://github.com/tambo-ai/tambo/blob/main/AGENTS.md) | Contributor guide outlining monorepo philosophy and standards |

## Summary

The **Tambo AI monorepo structure** organizes the codebase into a Turborepo workspace that balances separation of concerns with shared infrastructure:

- **Top-level directories** isolate the React SDK (`react-sdk/`), CLI tooling (`cli/`), demo showcase (`showcase/`), documentation (`docs/`), and cloud platform (`apps/`).
- **Shared packages** under `packages/` centralize core utilities, database schemas, backend helpers, and tooling configurations to ensure consistency.
- **Workspace imports** use scoped package names (e.g., `@tambo-ai/core`) with `"*"` versioning to enable cross-package dependencies without external publishing.
- **Automated synchronization** keeps UI components aligned between the CLI registry, showcase, and documentation sites.

## Frequently Asked Questions

### What is the difference between the `apps/` and `packages/` directories in the Tambo AI monorepo?

The `apps/` directory contains deployable applications, specifically the Tambo Cloud platform with its Next.js frontend (`apps/web`) and NestJS API server (`apps/api`). The `packages/` directory contains shared libraries that are imported by these applications and other workspaces, such as core utilities (`packages/core`), database schemas (`packages/db`), and configuration presets (`packages/eslint-config`).

### How does the React SDK relate to the other packages in the repository?

The `react-sdk/` directory is treated as a first-class workspace alongside `packages/`, containing the main `@tambo-ai/react` package. It imports shared utilities from `packages/core` and `packages/backend` while exposing its own hooks and providers through [`react-sdk/src/index.ts`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts). This structure allows the SDK to leverage centralized logic while maintaining independent versioning and release cycles.

### Where are shared ESLint and TypeScript configurations defined?

Shared tooling configurations reside in dedicated packages under the `packages/` directory. ESLint rules are defined in `packages/eslint-config/base.mjs`, TypeScript configurations in `packages/typescript-config/`, and Vite settings in `packages/vite-config/`. Each workspace references these via relative paths in their local configuration files, ensuring consistent linting and build behavior across the entire monorepo.

### What is the purpose of the `cli/src/registry/` directory?

The `cli/src/registry/` directory serves as the single source of truth for UI components that are distributed via the Tambo CLI. When components are generated or updated here, automated scripts synchronize them to both the `showcase/src/components/tambo/` and `docs/src/components/` directories. This ensures that the demo showcase and documentation site always display the latest component implementations without manual copying.