How get-convex/chef works
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)