# get-convex/chef architecture

> Architecture diagram of the GitHub repository get-convex/chef, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/get-convex/chef
- Repository: https://github.com/get-convex/chef

## Overview

##### Project Type and Purpose
- Chef is a full-stack web application – “the only AI app builder that knows backend.”
- It comprises a React/TypeScript frontend, serverless API routes, a reactive Convex database, an AI orchestration agent (chef-agent), a CLI (chefshot), plus supporting workers/proxies and test harnesses.

##### File Structure
- Top-Level Directories:
– app/ → Client-side React components, hooks, stores, styles, plus serverless routes under app/routes/.
– convex/ → Database schema, generated API, server functions, migrations, crons, rate limiters.
– chef-agent/ → Agentic loop: prompts, tool definitions, LLM provider integrations, context managers.
– chefshot/ → CLI tooling to interact with the Chef server.
– iframe-worker/ & proxy/ → Sandboxed execution & request proxying for secure code runs and API calls.
– template/ → Starter project template illustrating Convex + React integration.
– test-kitchen/ → Automated harness for testing chef-agent logic.
- Config/Infra: .github workflows, Convex configs, Tailwind, pnpm, tsconfig, .env files, Justfile, CI scripts.

##### Extract Architecture Insights from README
- “Built on Convex” – reactive DB exposing real-time APIs and edge functions.
- Supports zero-config auth (OAuth via Convex control plane).
- Includes background workflows (crons, agent loops).
- Exposes both web UI and CLI.

##### Main Components & Their Interactions
a. Frontend (UI Client)
– React pages & components (app/components, app/routes)
– Uses Convex client SDK for subscriptions & mutations
– Hosts WebContainer-based IDE (workbench/)
b. API Layer (Serverless Routes)
– Edge functions under app/routes (chat APIs, deploy endpoints, health checks)
– Deployed alongside Convex backend
c. Convex Backend (Database & Business Logic)
– Schema definitions & permissions (convex/schema.ts)
– Query/mutation endpoints (convex/*.ts)
– Background tasks (crons.ts), rate limiting, auth callbacks
d. Chef-Agent (AI Orchestration)
– System prompts, context management, tool invocation (chef-agent/)
– Integrates with LLM providers (OpenAI, Anthropic, Google, XAI)
– Writes results back to Convex or triggers other workflows
e. CLI (Chefshot)
– Command-line interface implementing scripts (chefshot/)
– Calls Convex REST/JS APIs and/or chef-agent tools
f. Supporting Services
– iframe-worker: secure in-browser sandbox for code execution
– proxy: bundled proxy for OpenAI or self-hosted endpoints

a. Components to Include
– Browser UI (React App)
– Serverless API Layer (app/routes functions)
– Convex Database & Edge Functions
– Chef-Agent Service
– Chefshot CLI
– Supporting Workers (iframe-worker, proxy)
– External Services (OAuth Provider, LLM Providers)
b. Relationships & Data Flow
– User ↔ React UI: HTTP/WebSocket
– UI → Serverless Routes → Convex DB (CRUD operations, real-time subscriptions)
– Chef-Agent ↔ Convex (reads chats, writes artifacts)
– Chef-Agent → LLM Providers (API calls)
– CLI → Convex & Chef-Agent (via Convex SDK or HTTP)
– iframe-worker/proxy mediate code execution & external API requests
– OAuth flow between UI and Convex control plane
c. Architectural Patterns & Principles
– Reactive database pattern (Convex pub/sub)
– Serverless functions for scaling API endpoints
– Agent loop pattern for AI orchestration
– Clear separation of concerns: UI, API, Data, Agent, CLI
d. Key Technologies & Frameworks
– React & Vite (frontend)
– Convex SDK & Edge Functions (backend)
– Typescript, pnpm, Tailwind CSS
– LLM provider SDKs (openai, anthropic, google)
– Node.js workers (iframe-worker, proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers Top-Down

    %% User and UI Layer
    subgraph "UI Layer" 
        direction TB
        User["User"]:::external
        Browser["Browser UI (React)"]:::frontend
        Browser -->|"interacts via HTTP/WebSocket"| User
    end
    click Browser "https://github.com/get-convex/chef/tree/main/app/"

    %% API Layer
    subgraph "Serverless API Layer" 
        direction TB
        APILayer["Edge Functions"]:::api
    end
    click APILayer "https://github.com/get-convex/chef/tree/main/app/routes/"

    %% Convex Backend
    subgraph "Convex Backend" 
        direction TB
        Schema["Schema Definitions"]:::db
        GeneratedAPI["Generated API & Models"]:::db
        BusinessLogic["Business Logic (Queries/Mutations)"]:::db
        Crons["Background Tasks (Crons)"]:::db
        RateLimiter["Rate Limiter"]:::db
    end
    click Schema "https://github.com/get-convex/chef/blob/main/convex/schema.ts"
    click GeneratedAPI "https://github.com/get-convex/chef/tree/main/convex/_generated/"
    click BusinessLogic "https://github.com/get-convex/chef/tree/main/convex/"
    click Crons "https://github.com/get-convex/chef/blob/main/convex/crons.ts"
    click RateLimiter "https://github.com/get-convex/chef/blob/main/convex/rateLimiter.ts"

    %% Chef-Agent Service
    subgraph "Chef-Agent Service" 
        direction TB
        AgentCore["Agent Loop"]:::agent
        Prompts["Prompts Definitions"]:::agent
        Tools["Tool Integrations"]:::agent
    end
    click AgentCore "https://github.com/get-convex/chef/tree/main/chef-agent/"
    click Prompts "https://github.com/get-convex/chef/tree/main/chef-agent/prompts/"
    click Tools "https://github.com/get-convex/chef/tree/main/chef-agent/tools/"

    %% CLI and Workers
    subgraph "CLI & Workers" 
        direction TB
        CLI["Chefshot CLI"]:::worker
        Iframe["iframe-worker"]:::worker
        Proxy["proxy"]:::worker
    end
    click CLI "https://github.com/get-convex/chef/tree/main/chefshot/"
    click Iframe "https://github.com/get-convex/chef/tree/main/iframe-worker/"
    click Proxy "https://github.com/get-convex/chef/tree/main/proxy/"

    %% Starter Template and Test Harness
    subgraph "Utilities" 
        direction TB
        Template["Starter Template"]:::utility
        TestHarness["Test Harness"]:::utility
    end
    click Template "https://github.com/get-convex/chef/tree/main/template/"
    click TestHarness "https://github.com/get-convex/chef/tree/main/test-kitchen/"

    %% Infra & Config
    subgraph "Config & Infra" 
        direction TB
        GitHubCI["GitHub Workflows"]:::infra
        Tailwind["Tailwind Config"]:::infra
        PNPM["pnpm-workspace.yaml"]:::infra
        TSConfig["tsconfig.json"]:::infra
    end
    click GitHubCI "https://github.com/get-convex/chef/tree/main/.github/"
    click Tailwind "https://github.com/get-convex/chef/blob/main/tailwind.config.ts"
    click PNPM "https://github.com/get-convex/chef/blob/main/pnpm-workspace.yaml"
    click TSConfig "https://github.com/get-convex/chef/blob/main/tsconfig.json"

    %% External Services
    subgraph "External Services" 
        direction TB
        OAuth["OAuth Provider"]:::external
        LLM["LLM Providers"]:::external
    end

    %% Connections
    Browser -->|"calls API"| APILayer
    APILayer -->|"CRUD, subscribe"| BusinessLogic
    BusinessLogic -->|"reads/writes"| Schema
    BusinessLogic --> GeneratedAPI
    Schema -->|"triggers"| Crons
    BusinessLogic --> RateLimiter

    BusinessLogic -->|"push updates"| Browser
    Browser -->|"exec code"| Iframe
    APILayer -->|"proxied API requests"| Proxy

    AgentCore -->|"reads/writes"| BusinessLogic
    AgentCore -->|"LLM request"| LLM
    Prompts --> AgentCore
    Tools --> AgentCore

    CLI -->|"SDK/API calls"| BusinessLogic
    CLI --> AgentCore

    Browser -->|"OAuth flow"| OAuth

    %% Legend (as a note)
    classDef frontend fill:#D0E8FF,stroke:#4A90E2;
    classDef api fill:#E6F4EA,stroke:#27AE60;
    classDef db fill:#FFEBD6,stroke:#E67E22;
    classDef agent fill:#F3E6FF,stroke:#8E44AD;
    classDef worker fill:#F2F2F2,stroke:#95A5A6;
    classDef utility fill:#FFF9C4,stroke:#F1C40F;
    classDef infra fill:#E8E8E8,stroke:#7F8C8D;
    classDef external fill:#E8F4FF,stroke:#3498DB;
```
