Skip to main content
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 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 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.
  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 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.