> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryzuko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# What is Zuko?

Zuko is an **open-source agentic CRM** that combines a modern CRM data model (contacts, companies, deals) with an **AI chat** experience. Every conversation can be grounded in a specific CRM entity so the AI always has the right customer, deal, or company in context.

***

## Tech stack

| Layer       | Technology                                           |
| ----------- | ---------------------------------------------------- |
| Frontend    | Next.js 16 + React 19 (App Router)                   |
| Backend     | NestJS 11                                            |
| Database    | PostgreSQL via Prisma ORM                            |
| Auth        | Better Auth (GitHub OAuth + optional email/password) |
| AI agents   | LangGraph (graph agents in TypeScript)               |
| Meeting bot | Puppeteer + Deepgram (Google Meet recording)         |
| Monorepo    | Nx + Bun 1.3.10 workspaces                           |

***

## Repository structure

### Apps

```
apps/
├── backend/          # NestJS API (port 3001)
├── web/              # Next.js frontend (port 3000)
├── ai-agents/        # LangGraph agents service (port 8080)
├── meeting-bot/      # Google Meet recording bot (port 8000)
├── web-e2e/          # Playwright E2E tests for web
├── backend-e2e/      # Backend E2E tests
└── ai-agents-e2e/    # AI agents E2E tests
```

### Libraries

```
libs/
├── models/           # Prisma schema, DB client, seeds
├── core/             # Shared utilities
├── ui-kit/           # Shared React components
├── sales/            # CRM domain: contacts, deals, companies
└── agents/           # AI agents library
```

***

## Prerequisites

Before setting up Zuko, make sure you have the following installed.

### Node.js 22

Zuko requires **Node.js 22** (matches the CI environment). Earlier versions will not work.

```bash theme={null}
node --version
# Should output v22.x.x
```

Install via [nvm](https://github.com/nvm-sh/nvm):

```bash theme={null}
nvm install 22
nvm use 22
```

### Bun 1.3.10+

Bun is used as the package manager and runtime across the monorepo.

```bash theme={null}
bun --version
# Should output 1.3.10 or higher
```

Install Bun:

```bash theme={null}
curl -fsSL https://bun.sh/install | bash
```

### PostgreSQL

Zuko uses PostgreSQL for all data storage. Any recent version works.

```bash theme={null}
# macOS
brew install postgresql@16
brew services start postgresql@16

# Verify
psql --version
pg_isready
```

### API keys

**Required:**

* **OpenAI API key** — for AI chat. Get one at [platform.openai.com](https://platform.openai.com)
* **GitHub OAuth credentials** — for authentication. Create an OAuth App at [github.com/settings/developers](https://github.com/settings/developers)

**Optional:**

* **LangSmith API key** — for agent tracing at [smith.langchain.com](https://smith.langchain.com)
* **Deepgram API key** — only needed for the meeting bot

***

## Core concepts

### CRM entities

**Contacts, companies, and deals** are the three core CRM entities, modeled in the database and exposed via the backend API.

### Agentic chat

An AI chat interface where conversations can be attached to any CRM entity, keeping AI responses grounded in real customer data.

### AI agents service

A separate LangGraph service (`apps/ai-agents`) that runs the agent logic and calls the backend via authenticated `/api/agents/*` endpoints.

### Meeting bot

Joins Google Meet calls, records audio, transcribes via Deepgram, and stores recordings in S3.

### MCP server

Zuko exposes an OAuth 2.1 MCP endpoint at `/api/mcp` so AI clients (Claude Desktop, Cursor, VS Code) can read and write CRM data on behalf of a logged-in user. See the [MCP server concept page](/concepts/mcp-server) for the full OAuth flow, available tools, and client setup.