> ## 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.

# Architecture Overview

Zuko is organized as an Nx monorepo. This page gives a high-level view of the main apps and libraries so you can navigate the codebase more easily.

## Apps

### Backend

`apps/backend` — NestJS API that handles auth, chat, and the sales domain (contacts, companies, deals).

### AI Agent

The AI agent runs **in-process inside the backend** (`apps/backend/src/agent/`). It is built on [DeepAgents](https://www.npmjs.com/package/deepagents) and uses a hierarchical sub-agent model (Contacts, Companies, Deals, Meetings). The agent activates when a user sends a chat message — no separate service is required. See the [AI Agents guide](/guides/ai-agents) for full details.

### Web

`apps/web` — Next.js frontend that provides the web UI and chat experience.

### Meeting Bot

`apps/meeting-bot` — Puppeteer-based bot that joins Google Meet calls, transcribes audio via Deepgram, and stores recordings in S3.

### Tests

* `apps/web-e2e` — Playwright-based E2E tests for the web app
* `apps/backend-e2e` — Backend end-to-end tests
* `apps/ai-agents-e2e` — AI agents end-to-end tests

***

## Libraries

### models

`libs/models` — Prisma schema, database client, migrations, and seed logic. Shared across backend and agents.

### sales

`libs/sales` — CRM domain logic for contacts, companies, and deals.

### ui-kit

`libs/ui-kit` — Shared React components used by the web app.

### core

`libs/core` — Shared utilities and helpers used across the monorepo.

***

## Data flow

1. The **web app** calls the **backend** (NestJS) for auth, chat, and CRM operations.
2. The backend uses **Prisma** (from `libs/models`) to read and write to PostgreSQL.
3. AI chat endpoints incorporate CRM context from `libs/sales`. The in-process **AI agent** executes CRM tool calls through the backend's `/api/agents/*` endpoints (authenticated via `AGENT_TOKEN`) and can run code inside a [sandbox](/concepts/sandbox).
4. UI components from `libs/ui-kit` render CRM entities and chat interfaces in the web app.
5. When the agent needs to execute code or access files, it does so inside a **sandbox** — an isolated environment managed by `SandboxLifecycleService`. In production, sandboxes run on Sprites (Fly.io); in development they fall back to local `child_process` execution. See [Sandbox](/concepts/sandbox) for details.

***

## Testing and tooling

### E2E tests

E2E tests live in `apps/web-e2e` and use Playwright with Nx.

### Task orchestration

Nx provides task orchestration (`nx run`, `nx affected`) for builds, tests, and linting across the monorepo.

### Issue tracking

Beads (`.beads/`) is used for issue tracking so issues stay version-controlled inside the repo.