# Add Convex Backend Support to Dyad

> Generated by swarm planning session on 2026-02-12

## Summary

Add Convex as a third backend option in Dyad (alongside Supabase and Neon), enabling users to build apps with real-time reactive data, serverless functions, and file storage — all without SQL. This positions Dyad as the long-term successor to Chef (the Convex-native builder in `chef/`), porting Chef's battle-tested prompts and patterns into Dyad's backend-flexible architecture.

## Problem Statement

Dyad users currently have two backend options: Supabase and Neon, both PostgreSQL-based. Users building apps that need real-time reactivity, serverless functions, or document-based data models are forced into SQL paradigms or must leave Dyad entirely (using Chef or building manually). Adding Convex expands Dyad's addressable use cases and aligns with the **Backend-Flexible** design principle.

Target users:

1. **Existing Dyad users** wanting reactive, real-time apps without managing WebSocket infrastructure
2. **Convex developers** seeking an AI-assisted builder for their preferred backend
3. **New users** attracted by Convex's simpler DX (no SQL, no ORM, no migrations — just TypeScript)

## Scope

### In Scope (MVP)

- **Deploy key connection flow** — User pastes a Convex deploy key + deployment URL to connect an existing Convex project to a Dyad app. "Open Convex Dashboard" link via `ipc.system.openExternalUrl` for easy key retrieval. Deploy key field uses `type="password"` with show/hide toggle. Inline validation errors (not toasts).
- **Convex-aware agent prompts** — High-fidelity port of Chef's `convexGuidelines.ts` (~960 lines) and `solutionConstraints.ts` for Dyad's tool set and execution model. This is the highest-value item. Since Dyad is the long-term Chef successor, invest in prompt quality (budget 3-4 days, not a quick copy).
- **Convex context injection** — Before each chat turn, read `convex/schema.ts` from the app's files and inject schema context into the AI prompt.
- **Dual dev server via `concurrently`** — Template start script runs both `npx convex dev` and `npx vite` via `concurrently --names "vite,convex"`. Uses existing `startCommand` column — no process manager changes needed. Console output prefixed with process names for error attribution.
- **Deploy approval gate** — After the AI generates/modifies Convex schema or functions, show a confirmation before running `npx convex deploy`. Leverages existing tool consent system.
- **Convex template** — Fork Chef's template (`chef/template/`) as starting point. Pre-wired with `convex/` directory, `convex.config.ts`, `ConvexProvider`, correct start scripts, `convex` + `concurrently` npm dependencies, Tailwind + shadcn/ui compatibility. Production-quality since Dyad replaces Chef long-term.
- **IPC contracts and handlers** — Following the Neon pattern for connect/disconnect/get-project-info/deploy/get-schema.
- **ConvexConnector UI** — Card-based integration on App Details page with two primary states: disconnected (key input + dashboard link + connect button) and connected (project badge + dashboard link + disconnect button). Simpler than Supabase connector since no team/project selection needed.
- **Connection status indicator** — Small status badge in preview panel toolbar or chat header showing Convex connection state at a glance (ported from Chef's `ConvexConnection.tsx` pattern).
- **Backend mutual exclusivity** — Convex is mutually exclusive with Supabase/Neon per app in v1. Gray out other backend connectors when one is active.
- **Onboarding card** — First-time "What to expect" card explaining: Convex requires internet, schema deploys automatically in dev mode, functions are TypeScript not SQL.
- **Dashboard link** — "View in Convex Dashboard" link in connected state (trivially cheap, improves connected state UX).
- **Agent tools** — `get_convex_project_info`, `get_convex_schema`, `deploy_convex` for local-agent mode. Also `<dyad-add-integration provider="convex">` support in agent responses for suggesting Convex when appropriate.
- **Disconnect flow** — Confirmation dialog: "Disconnect from Convex? Your local Convex files will be kept. The Convex project will not be deleted." Unlinks project reference without deleting anything (matches Supabase `handleUnsetProject` pattern).
- **Dependency management** — Agent prompt instructs `npm install convex` when adding Convex to an app. Template includes `convex` and `concurrently` as dependencies.

### Out of Scope (Follow-up)

- **OAuth authentication** — Replace deploy key paste with OAuth flow via `oauth.dyad.sh` (v2)
- **Auto-provision new Convex projects** — Requires account-level auth; v1 is "connect existing" only
- **Convex Auth integration** — `@convex-dev/auth` with username/password/OAuth login (v2)
- **Convex Components support** — ProseMirror, presence, and other library-level features
- **Production vs. development deployment management** — Dev-only in v1
- **Environment variable management UI** — Users set env vars in Convex Dashboard for v1
- **Functions viewer** — Listing queries/mutations/actions requires TS parsing or deployment API; defer to v2
- **Backend switching** — No switching from Supabase/Neon to Convex or vice versa. Users create new apps.
- **Convex-specific templates in template gallery** — v1 uses a single starter template; showcase templates (real-time chat, collaborative todo) are follow-ups

## User Stories

1. **As a Dyad user**, I want to connect my existing Convex project to a Dyad app so that I can build apps with real-time data and serverless functions.
2. **As a Dyad user**, I want the AI agent to generate correct Convex code (schema, queries, mutations, actions) so that my app works without manual debugging.
3. **As a Dyad user**, I want my Convex functions to auto-sync during development (via `npx convex dev`) so that I see live data in the preview immediately.
4. **As a Dyad user**, I want to approve schema deployments before they push to production so that I understand what's changing.
5. **As a Dyad user**, I want the AI to know my current Convex schema so that it generates code consistent with my existing tables and indexes.
6. **As a first-time Convex user**, I want clear guidance on what Convex is and how it differs from SQL so that I can make an informed backend choice.

## UX Design

### User Flow

**Primary flow: Connecting Convex to an existing app**

1. User navigates to **App Details** page for their app
2. User sees **Convex integration card** in disconnected state with Convex branding and description: "Real-time reactive backend — no SQL needed"
3. User clicks **"Connect to Convex"** button
4. Dyad opens Convex Dashboard deploy key page in browser (via `ipc.system.openExternalUrl`) with inline instructions: "Copy your deployment URL and deploy key from the Convex Dashboard"
5. User pastes **deployment URL** and **deploy key** into two input fields
6. Dyad validates the credentials (test API call)
7. **Connected state** shows: project name badge, team name, "View in Convex Dashboard" link, disconnect button
8. **First-time onboarding card** appears (dismissable): explains Convex requires internet, uses TypeScript functions not SQL, schema syncs automatically in dev mode
9. User describes their app in chat. AI generates Convex-specific code.

### Key States

- **Disconnected**: Convex logo, "Connect to Convex" button, one-line value prop
- **Connecting**: Spinner with "Validating Convex credentials..." label
- **Connected**: Project name badge, team name, dashboard link, disconnect button
- **Error**: Error callout with specific message, retry button, "Try different credentials" option
- **First-run**: Onboarding card with "What to expect" content (dismissable, shown once via `hasSeenConvexOnboarding` flag)

### Interaction Details

- **Deploy key input**: Two text fields (deployment URL + deploy key) with paste support and clear labels
- **Schema viewer**: "View Schema" button opens `convex/schema.ts` in the existing CodeView panel (Monaco editor, read-only). No custom schema visualization component needed — the schema IS the TypeScript file.
- **Deploy approval**: After AI modifies Convex files, a chat card shows schema diff with "Deploy to Convex" button. Uses existing tool consent system (`mcp_tool_consents`).
- **Console output**: Convex dev server logs interleaved with Vite logs. Convex lines tagged with `[Convex]` prefix for visual differentiation. Console component can filter/color-code based on source tag.
- **Disconnect**: Confirmation dialog: "This will disconnect the Convex project. Your Convex project and local files will not be deleted." Unlinks project without deleting anything.

### Accessibility

- Deploy key input fields: proper `<label>` elements, placeholder text, `aria-describedby` for instructions
- Connection status changes announced via `aria-live` region
- Team/project info: semantic headings and landmarks
- Onboarding card: dismissable via keyboard (Escape), focus trapped while visible
- Console log source indicators: not color-only — include text prefix `[Convex]`

## Technical Design

### Architecture

Follows Dyad's existing layered IPC pattern:

```
UI (ConvexConnector.tsx) → IPC Contracts (convex.ts) → Handlers (convex_handlers.ts) → CLI/API
```

**CLI-driven approach (not full API client)**: Use `npx convex` CLI commands for deploy operations, read `convex/schema.ts` directly for schema introspection. This mirrors how Chef works and minimizes API surface risk.

**Dual dev server**: Template's `package.json` uses `concurrently` to run both `npx convex dev` and `npx vite`. Dyad's existing `startCommand` column supports custom start scripts — no changes to `app_handlers.ts` process management.

### Components Affected

**New files (6 + template):**
| File | Purpose | Size |
|------|---------|------|
| `src/ipc/types/convex.ts` | IPC contracts (connect, disconnect, get-info, deploy, get-schema) | Small |
| `src/ipc/handlers/convex_handlers.ts` | Handler implementations | Medium |
| `src/convex_admin/convex_management_client.ts` | Deploy key validation, deployment status checks via HTTP API | Small |
| `src/convex_admin/convex_context.ts` | Context generator — reads `convex/schema.ts`, formats for AI prompt | Small |
| `src/prompts/convex_prompt.ts` | Convex-specific system prompt (high-fidelity port from Chef's `convexGuidelines.ts` + `solutionConstraints.ts`) | Large |
| `src/components/ConvexConnector.tsx` | Deploy key paste UI + connected state (no separate integration file needed — scope is smaller than Supabase) | Medium |
| Convex template repo | Fork of Chef's template, adapted for Dyad: `convex/`, `ConvexProvider`, `concurrently` start scripts, Tailwind | Medium |

Note: No `convex_return_handler.ts` needed (no OAuth). No separate `ConvexIntegration.tsx` needed (folded into ConvexConnector since scope is simpler). Deploy key storage is per-app in the `apps` table, NOT in global settings.

**Modified files:**
| File | Change | Size |
|------|--------|------|
| `src/db/schema.ts` | Add `convexDeploymentUrl`, `convexProjectSlug`, `convexTeamSlug` to `apps` table | Small |
| `src/ipc/handlers/chat_stream_handlers.ts` | Add Convex context injection branch (parallel to Supabase block ~line 726) | Small |
| `src/pro/main/ipc/handlers/local_agent/tool_definitions.ts` | Add Convex agent tools | Medium |
| `src/prompts/local_agent_prompt.ts` | Add Convex-aware instructions | Small |
| `src/pages/app-details.tsx` | Add ConvexConnector to integrations section | Small |

### Data Model Changes

**SQLite schema (`apps` table) — new nullable text columns:**

```sql
ALTER TABLE apps ADD COLUMN convex_deployment_url TEXT;
ALTER TABLE apps ADD COLUMN convex_deploy_key TEXT;
ALTER TABLE apps ADD COLUMN convex_project_slug TEXT;
ALTER TABLE apps ADD COLUMN convex_team_slug TEXT;
```

Deploy keys stored at the **app level** (not settings level) since Convex uses per-deployment keys. This differs from Supabase (org-level) and Neon (account-level) credential storage.

Drizzle migration required — straightforward `ALTER TABLE ADD COLUMN` for nullable text fields.

**Security note:** Deploy keys are stored as plain text in SQLite for v1 (same trust model as local git credentials). For v2, consider using Electron's `safeStorage` API to encrypt sensitive tokens at rest — this would benefit all backend integrations, not just Convex.

**Settings additions:**

- `hasSeenConvexOnboarding: boolean` — tracks whether user has dismissed onboarding card

### API Changes

**New IPC contracts (`src/ipc/types/convex.ts`):**

- `convex:connect-project` — Validate and store deploy key + deployment URL for an app
- `convex:disconnect-project` — Remove Convex association from an app
- `convex:get-project-info` — Return deployment URL, project slug, team slug
- `convex:deploy` — Execute `npx convex deploy` in the app directory
- `convex:get-schema` — Read and return contents of `convex/schema.ts`

**New agent tools:**

- `get_convex_project_info` — Returns deployment info for context
- `get_convex_schema` — Returns schema file contents
- `deploy_convex` — Triggers `npx convex deploy` (with approval gate)

### Key Technical Decisions

1. **CLI-driven, not API client**: Use `npx convex` for operations. No official management SDK exists for Convex. Raw HTTP calls where needed.
2. **Schema = file read**: No SQL introspection needed. `convex/schema.ts` IS the schema. Simpler than Supabase/Neon.
3. **`concurrently` for dual process**: Template start script handles both dev servers. Existing `startCommand` column supports this without architecture changes.
4. **High-fidelity prompt port, not copy-paste**: Chef's `convexGuidelines.ts` and `solutionConstraints.ts` reference WebContainer and Chef-specific tools. Needs dedicated adaptation for Dyad's tool set (3-4 days). Since Dyad replaces Chef long-term, invest in prompt quality and track Chef's prompt updates for backporting improvements.
5. **`convex/_generated/` directory**: Must be in `.gitignore`, agent prompt must say "never edit files in `convex/_generated/`", file tree UI should hide or gray out generated files.
6. **Use "backend" not "database" in UI**: Convex is a reactive backend platform, not a database. Audit all labels to avoid "database" when referring to Convex.

## Implementation Plan

**Estimated effort: 14-20 engineering days (3-4 weeks).** Checkpoint at week 2 to assess pace.

### Phase 1: Template + Foundation (Week 1)

- [ ] Fork Chef's template (`chef/template/`), adapt for Dyad: `convex/` directory, `convex.config.ts`, `ConvexProvider` setup, `concurrently --names "vite,convex"` in start script, `convex` + `concurrently` dependencies, Tailwind + shadcn/ui compatibility
- [ ] Add Convex columns to `apps` table (`convex_deployment_url`, `convex_deploy_key`, `convex_project_slug`, `convex_team_slug`) via Drizzle migration
- [ ] Define IPC contracts in `src/ipc/types/convex.ts` following Neon pattern
- [ ] Implement `convex_handlers.ts` with connect/disconnect/get-info/deploy/get-schema handlers
- [ ] Implement `convex_management_client.ts` for deploy key validation
- [ ] Build `ConvexConnector.tsx` with deploy key paste flow (`type="password"` input, inline validation, "Open Convex Dashboard" link)

### Phase 2: AI Integration (Weeks 2-3)

- [ ] High-fidelity port of Chef's `convexGuidelines.ts` + `solutionConstraints.ts` to `src/prompts/convex_prompt.ts` — systematically replace WebContainer/Chef tool references with Dyad equivalents (budget 3-4 days)
- [ ] Implement `convex_context.ts` — reads `convex/schema.ts` and formats for AI prompt
- [ ] Wire Convex context injection into `chat_stream_handlers.ts` (mutually exclusive with Supabase/Neon)
- [ ] Add Convex-specific instructions to `local_agent_prompt.ts`
- [ ] Implement agent tools: `get_convex_project_info`, `get_convex_schema`, `deploy_convex`
- [ ] Add `<dyad-add-integration provider="convex">` support in agent responses
- [ ] Add ConvexConnector to App Details page integrations section
- [ ] Implement onboarding card ("What to expect with Convex")
- [ ] Add connection status indicator in preview panel toolbar
- [ ] Add "View in Convex Dashboard" link in connected state
- [ ] Implement deploy approval gate via tool consent system
- [ ] Add Convex logo/branding assets (light + dark variants)

### Phase 3: Testing + Hardening (Week 4)

- [ ] Unit tests for IPC contracts (Zod schema validation)
- [ ] Unit tests for `convex_management_client.ts` (mocked HTTP)
- [ ] Create `fakeConnect` test-only handlers following Neon/Supabase pattern
- [ ] E2E Playwright tests for ConvexConnector UI flow
- [ ] Integration test: create app → connect Convex → AI generates code → deploy
- [ ] Prompt regression tests: verify Convex prompt generates valid Convex code
- [ ] Console log tagging: recognize Convex-prefixed output in Console component
- [ ] Handle `convex/_generated/` in gitignore, agent prompts, and file tree UI
- [ ] Disconnect flow with confirmation dialog
- [ ] Error handling: invalid deploy key, network failure during dev, Convex CLI not found

## Testing Strategy

- [ ] **Unit tests**: IPC contracts (Zod validation), management client (mocked HTTP responses), context generator (mock file reads)
- [ ] **Integration tests**: Full flow from connect → AI generation → deploy, using `fakeConnect` pattern from existing backends
- [ ] **E2E tests**: Playwright tests for ConvexConnector UI component (connect, disconnect, error states)
- [ ] **Prompt regression**: Verify AI generates valid Convex code patterns (schema with validators, queries/mutations with correct function signatures, proper `ConvexProvider` setup)
- [ ] **Error scenarios**: Invalid deploy key, network failure during deploy, Convex CLI not installed, `convex/schema.ts` not found, destructive schema changes

## Risks & Mitigations

| Risk                                                                               | Likelihood | Impact | Mitigation                                                                                                   |
| ---------------------------------------------------------------------------------- | ---------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| AI generates incorrect Convex code (wrong validators, invalid function signatures) | Medium     | High   | Port Chef's battle-tested ~960-line prompt; dedicated prompt adaptation time (2-3 days)                      |
| Console log interleaving confuses users (Vite vs Convex output)                    | High       | Medium | Tag Convex output with `[Convex]` prefix; add log source filtering in Console component                      |
| Users hit Convex free tier limits during rapid AI iteration                        | Medium     | Medium | Surface pricing info in onboarding card; link to Convex pricing docs                                         |
| Convex CLI not available / wrong Node.js version                                   | Medium     | Medium | Clear error message: "Convex CLI not found"; prerequisite check before connecting                            |
| Network failure during `npx convex dev` breaks live preview                        | High       | Medium | Clear error state in console; retry guidance; note in onboarding card that Convex requires internet          |
| Chef prompt assumes WebContainer / Chef-specific tools                             | High       | High   | Dedicated prompt adaptation sprint; do NOT copy-paste — systematically replace tool references               |
| `convex/_generated/` files edited by agent or committed to git                     | Medium     | Medium | Agent prompt exclusion rule; `.gitignore` entry in template; file tree UI grays out generated files          |
| Deploy key stored as plain text in SQLite                                          | Low        | Medium | Acceptable for v1 (local desktop app trust model). v2: use Electron `safeStorage` API for encryption at rest |
| No offline development possible with Convex                                        | High       | Low    | Clear messaging in onboarding card: "Convex requires internet connection during development"                 |

## Open Questions

1. **Convex branding assets** — Do we need permission from Convex to use their logo in Dyad? Check trademark guidelines.
2. **Template hosting** — Should the Convex template be a new GitHub repo (like existing templates) or a fork of Chef's template adapted for Dyad?
3. **Token budget for Convex prompt** — The ~960-line prompt from Chef is substantial. May need to be selective for smaller LLM models. Profile token usage and trim if needed.
4. **Vercel deployment + Convex** — When deploying to Vercel, the `CONVEX_URL` env var needs to be set. Should this be automated or manual? (Follow-up work.)
5. **Chef feature parity roadmap** — Since Dyad is the long-term Chef successor, define concrete feature parity milestones. Chef has capabilities Dyad doesn't: WebContainer-based sandboxed execution, sharing/forking projects, social shares with thumbnails, Convex Components support (proseMirror, presence, resend). Plan a follow-up session after MVP ships to create a "Chef parity checklist."

## Decision Log

| Decision                                   | Reasoning                                                                                                                                                                                          | Alternatives Considered                                                                                                                                                  |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Deploy key paste for auth (v1)             | Simplest to implement, proven in Chef, no server-side OAuth work needed. OAuth deferred to v2.                                                                                                     | OAuth via oauth.dyad.sh (too much server-side work for v1), CLI login (breaks Dyad UX pattern), hybrid deep-link (middle ground — we DO deep-link to the Dashboard page) |
| Connect existing project only (v1)         | Auto-provisioning requires account-level auth, significantly expanding scope. Users create projects on Convex Dashboard first.                                                                     | Auto-provision like Chef (requires full Convex account auth)                                                                                                             |
| Dual dev server via `concurrently` (MVP)   | Without `npx convex dev`, live preview is non-functional for Convex apps. Uses existing `startCommand` column — no process manager refactor needed.                                                | Manual deploy button only (broken default DX), modify process manager (too large a refactor)                                                                             |
| Backend mutual exclusivity (v1)            | Simpler conditional logic, clearer mental model, avoids conflicting prompts. Just another branch in `chat_stream_handlers.ts`.                                                                     | Allow Convex + Supabase (massively complicates prompts and UX)                                                                                                           |
| CLI-driven approach (not API client)       | Mirrors how Chef works, minimizes API surface risk, no official Convex management SDK. Uses `npx convex` for deploy.                                                                               | Full API client (more work, fragile against Convex API changes)                                                                                                          |
| Schema = file read (not SQL introspection) | Convex schema IS the `convex/schema.ts` file. Reading it directly is instant and always in sync. Simpler than Supabase/Neon SQL introspection.                                                     | Query deployment API for schema (requires running deployment, adds latency)                                                                                              |
| Replace Chef long-term                     | Dyad's Convex integration is the long-term successor to Chef. Invest in feature parity. Port prompts and patterns.                                                                                 | Keep Chef and Dyad complementary (duplicated effort), port Chef into Dyad entirely (too large)                                                                           |
| High-fidelity prompt port (3-4 days)       | Chef's prompt references WebContainer and Chef-specific tools. Naive copy causes broken tool references. Since Dyad replaces Chef, invest in prompt quality.                                       | Verbatim copy (broken references), write from scratch (loses battle-tested content), quick adaptation (insufficient for Chef replacement goal)                           |
| Onboarding card in v1                      | Near-zero engineering overhead (pure React component + boolean flag). High UX value for explaining Convex differences from SQL backends.                                                           | Defer to v2 (users confused by paradigm differences)                                                                                                                     |
| Template from Chef fork (step 1)           | Having a working template unblocks all subsequent testing. Chef's template is battle-tested for Convex.                                                                                            | Build from scratch (slower), use generic Convex starter (may not match Dyad's needs)                                                                                     |
| Per-app deploy key storage                 | Convex uses per-deployment keys (unlike Supabase org-level or Neon account-level). Store in `apps` table, not global settings. Settings page should NOT show Convex — it only makes sense per-app. | Global settings (wrong abstraction for per-deployment keys)                                                                                                              |

---

_Generated by dyad:swarm-to-plan_
