# sunnyvbi/zavi architecture

> Architecture diagram of the GitHub repository sunnyvbi/zavi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sunnyvbi/zavi
- Repository: https://github.com/sunnyvbi/zavi

## Overview

Zavi is a multi-client AI-agent workspace with a backend for agent execution and growth-channel runs, a web workspace for initiating and reviewing engineering work, and an admin console. A typical engineering flow starts with a user request in the workspace, proceeds through backend agent and sandbox services, and returns build/preview status to the workspace; the sampled excerpts do not show the complete request-to-run wiring, so that connection is marked unverified. The repository also includes a database connector, browser extension, mobile client, and broad admin capabilities. Evidence is limited to the supplied excerpts and source index; the README is empty.

Main entry points: [`apps/web/src/components/workspace/agent/EngineerDashboard.tsx`](https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/components/workspace/agent/EngineerDashboard.tsx) (Engineer dashboard), [`apps/connector/src/runtime.ts`](https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/runtime.ts) (Connector runtime), [`apps/backend/src/services/channels/engine.ts`](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/engine.ts) (Channel run engine), [`apps/web/src/lib/workspace/useBuildPreview.ts`](https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/lib/workspace/useBuildPreview.ts) (Build preview state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["User workspace"]
  node_web_engineer["Engineer dashboard"]
  node_web_shell["Workspace shell<br/>[WorkspaceShell.tsx]"]
  node_build_preview_hook["Build preview state<br/>[useBuildPreview.ts]"]
  node_site_preview["Engineer site preview"]
  node_extension_panel["Browser assistant<br/>[App.tsx]"]
  node_mobile_dictation["Mobile dictation<br/>[useDictation.ts]"]
end

subgraph group_backend["Agent backend"]
  node_engine_agent["Agent engine<br/>[openai-engine.ts]"]
  node_tool_search["Tool search<br/>[tool-search.ts]"]
  node_engineer_preview["Preview service"]
  node_sandbox_client["Sandbox client<br/>[e2b-client.ts]"]
  node_preview_route["Preview route"]
  node_postdeploy_verify["Post-deploy verification"]
  node_worker_client["Worker client<br/>[client.ts]"]
end

subgraph group_growth["Growth channels"]
  node_channel_engine["Channel run engine<br/>[engine.ts]"]
  node_channel_claim["Run claim<br/>[claim.ts]"]
  node_channel_budget["Run budget<br/>[budget.ts]"]
  node_channel_actions["Channel actions<br/>[top-actions.ts]"]
end

subgraph group_connector["Database connector"]
  node_connector_main["Connector bootstrap<br/>[main.ts]"]
  node_connector_runtime["Connector runtime<br/>[runtime.ts]"]
  node_connector_server["Local admin server<br/>[server.ts]"]
  node_connector_db["Database manager<br/>[index.ts]"]
  node_connector_client["Backend client<br/>[client.ts]"]
  node_connector_execute["Query executor<br/>[execute.ts]"]
end

subgraph group_operations["Admin operations"]
  node_admin_tenant["Tenant operations<br/>[page.tsx]"]
  node_admin_context["Suggestion context"]
  node_admin_api["Admin API client<br/>[api-admin.ts]"]
end

node_user(("Workspace user"))

node_user -->|"requests work"| node_web_engineer
node_web_engineer -->|"reads workspace"| node_web_shell
node_web_engineer -.->|"submits agent work"| node_engine_agent
node_web_engineer -.->|"tracks build"| node_build_preview_hook
node_build_preview_hook -.->|"provides preview state"| node_site_preview
node_build_preview_hook -.->|"requests preview data"| node_preview_route
node_preview_route -->|"uses preview service"| node_engineer_preview
node_engineer_preview -->|"runs sandbox commands"| node_sandbox_client
node_engine_agent -->|"uses tool search"| node_tool_search
node_postdeploy_verify -->|"registers worker"| node_worker_client
node_channel_engine -->|"claims run"| node_channel_claim
node_channel_engine -->|"checks budget"| node_channel_budget
node_channel_engine -->|"resolves action"| node_channel_actions
node_connector_main -->|"starts runtime"| node_connector_runtime
node_connector_main -->|"starts local server"| node_connector_server
node_connector_runtime -->|"executes checked request"| node_connector_execute
node_connector_runtime -->|"calls backend"| node_connector_client
node_connector_runtime -->|"uses database manager"| node_connector_db
node_connector_server -->|"uses database manager"| node_connector_db
node_admin_context -->|"fetches context"| node_admin_api

click node_web_engineer "https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/components/workspace/agent/EngineerDashboard.tsx"
click node_web_shell "https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/components/workspace/WorkspaceShell.tsx"
click node_build_preview_hook "https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/lib/workspace/useBuildPreview.ts"
click node_site_preview "https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/components/workspace/EngineerSitePreview.tsx"
click node_engine_agent "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/agents/engine/openai-engine.ts"
click node_tool_search "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/agents/engine/tool-search.ts"
click node_engineer_preview "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/sandbox/engineer-preview.ts"
click node_sandbox_client "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/sandbox/e2b-client.ts"
click node_preview_route "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/routes/workspace/engineer-preview.ts"
click node_postdeploy_verify "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/workers/functions/engineer-postdeploy-verify.ts"
click node_worker_client "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/workers/client.ts"
click node_channel_engine "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/engine.ts"
click node_channel_claim "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/claim.ts"
click node_channel_budget "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/budget.ts"
click node_channel_actions "https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/top-actions.ts"
click node_connector_main "https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/main.ts"
click node_connector_runtime "https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/runtime.ts"
click node_connector_server "https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/local/server.ts"
click node_connector_db "https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/db/index.ts"
click node_connector_client "https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/client.ts"
click node_connector_execute "https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/execute.ts"
click node_admin_tenant "https://github.com/sunnyvbi/zavi/blob/main/apps/admin/src/app/(dashboard)/tenants/%5Bid%5D/page.tsx"
click node_admin_context "https://github.com/sunnyvbi/zavi/blob/main/apps/admin/src/components/admin/suggestions/workspace/useClientContext.ts"
click node_admin_api "https://github.com/sunnyvbi/zavi/blob/main/apps/admin/src/lib/api-admin.ts"
click node_extension_panel "https://github.com/sunnyvbi/zavi/blob/main/apps/extension/src/panel/App.tsx"
click node_mobile_dictation "https://github.com/sunnyvbi/zavi/blob/main/apps/mobile/src/features/voice/useDictation.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_engineer,node_web_shell,node_build_preview_hook,node_site_preview,node_extension_panel,node_mobile_dictation,node_user toneBlue
class node_engine_agent,node_tool_search,node_engineer_preview,node_sandbox_client,node_preview_route,node_postdeploy_verify,node_worker_client toneAmber
class node_channel_engine,node_channel_claim,node_channel_budget,node_channel_actions toneMint
class node_connector_main,node_connector_runtime,node_connector_server,node_connector_db,node_connector_client,node_connector_execute toneRose
class node_admin_tenant,node_admin_context,node_admin_api toneIndigo
```

## Components

### User workspace

- [Engineer dashboard](https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/components/workspace/agent/EngineerDashboard.tsx): `apps/web/src/components/workspace/agent/EngineerDashboard.tsx`
- [Workspace shell](https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/components/workspace/WorkspaceShell.tsx): `apps/web/src/components/workspace/WorkspaceShell.tsx`
- [Build preview state](https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/lib/workspace/useBuildPreview.ts): `apps/web/src/lib/workspace/useBuildPreview.ts`
- [Engineer site preview](https://github.com/sunnyvbi/zavi/blob/main/apps/web/src/components/workspace/EngineerSitePreview.tsx): `apps/web/src/components/workspace/EngineerSitePreview.tsx`
- [Browser assistant](https://github.com/sunnyvbi/zavi/blob/main/apps/extension/src/panel/App.tsx): `apps/extension/src/panel/App.tsx`
- [Mobile dictation](https://github.com/sunnyvbi/zavi/blob/main/apps/mobile/src/features/voice/useDictation.ts): `apps/mobile/src/features/voice/useDictation.ts`

### Agent backend

- [Agent engine](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/agents/engine/openai-engine.ts): `apps/backend/src/services/agents/engine/openai-engine.ts`
- [Tool search](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/agents/engine/tool-search.ts): `apps/backend/src/services/agents/engine/tool-search.ts`
- [Preview service](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/sandbox/engineer-preview.ts): `apps/backend/src/services/sandbox/engineer-preview.ts`
- [Sandbox client](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/sandbox/e2b-client.ts): `apps/backend/src/services/sandbox/e2b-client.ts`
- [Preview route](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/routes/workspace/engineer-preview.ts): `apps/backend/src/routes/workspace/engineer-preview.ts`
- [Post-deploy verification](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/workers/functions/engineer-postdeploy-verify.ts): `apps/backend/workers/functions/engineer-postdeploy-verify.ts`
- [Worker client](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/workers/client.ts): `apps/backend/workers/client.ts`

### Growth channels

- [Channel run engine](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/engine.ts): `apps/backend/src/services/channels/engine.ts`
- [Run claim](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/claim.ts): `apps/backend/src/services/channels/claim.ts`
- [Run budget](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/budget.ts): `apps/backend/src/services/channels/budget.ts`
- [Channel actions](https://github.com/sunnyvbi/zavi/blob/main/apps/backend/src/services/channels/top-actions.ts): `apps/backend/src/services/channels/top-actions.ts`

### Database connector

- [Connector bootstrap](https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/main.ts): `apps/connector/src/main.ts`
- [Connector runtime](https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/runtime.ts): `apps/connector/src/runtime.ts`
- [Local admin server](https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/local/server.ts): `apps/connector/src/local/server.ts`
- [Database manager](https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/db/index.ts): `apps/connector/src/db/index.ts`
- [Backend client](https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/client.ts): `apps/connector/src/client.ts`
- [Query executor](https://github.com/sunnyvbi/zavi/blob/main/apps/connector/src/execute.ts): `apps/connector/src/execute.ts`

### Admin operations

- [Tenant operations](https://github.com/sunnyvbi/zavi/blob/main/apps/admin/src/app/(dashboard)/tenants/%5Bid%5D/page.tsx): `apps/admin/src/app/(dashboard)/tenants/[id]/page.tsx`
- [Suggestion context](https://github.com/sunnyvbi/zavi/blob/main/apps/admin/src/components/admin/suggestions/workspace/useClientContext.ts): `apps/admin/src/components/admin/suggestions/workspace/useClientContext.ts`
- [Admin API client](https://github.com/sunnyvbi/zavi/blob/main/apps/admin/src/lib/api-admin.ts): `apps/admin/src/lib/api-admin.ts`

### Other components

- **Workspace user**

## Connections

- Workspace user → Engineer dashboard: requests work (evidence: `apps/web/src/components/workspace/agent/EngineerDashboard.tsx`)
- Engineer dashboard → Workspace shell: reads workspace (evidence: `apps/web/src/components/workspace/agent/EngineerDashboard.tsx`)
- Engineer dashboard → Agent engine: submits agent work
- Engineer dashboard → Build preview state: tracks build
- Build preview state → Engineer site preview: provides preview state
- Build preview state → Preview route: requests preview data
- Preview route → Preview service: uses preview service (evidence: `apps/backend/src/routes/workspace/engineer-preview.ts`)
- Preview service → Sandbox client: runs sandbox commands (evidence: `apps/backend/src/services/sandbox/engineer-preview.ts`)
- Agent engine → Tool search: uses tool search (evidence: `apps/backend/src/services/agents/engine/openai-engine.ts`)
- Post-deploy verification → Worker client: registers worker (evidence: `apps/backend/workers/functions/engineer-postdeploy-verify.ts`)
- Channel run engine → Run claim: claims run (evidence: `apps/backend/src/services/channels/engine.ts`)
- Channel run engine → Run budget: checks budget (evidence: `apps/backend/src/services/channels/engine.ts`)
- Channel run engine → Channel actions: resolves action (evidence: `apps/backend/src/services/channels/engine.ts`)
- Connector bootstrap → Connector runtime: starts runtime (evidence: `apps/connector/src/main.ts`)
- Connector bootstrap → Local admin server: starts local server (evidence: `apps/connector/src/main.ts`)
- Connector runtime → Query executor: executes checked request (evidence: `apps/connector/src/runtime.ts`)
- Connector runtime → Backend client: calls backend (evidence: `apps/connector/src/runtime.ts`)
- Connector runtime → Database manager: uses database manager (evidence: `apps/connector/src/runtime.ts`)
- Local admin server → Database manager: uses database manager (evidence: `apps/connector/src/local/server.ts`)
- Suggestion context → Admin API client: fetches context (evidence: `apps/admin/src/components/admin/suggestions/workspace/useClientContext.ts`)
