Add convex backend support plan (#2693)

plans/convex-backend-support.md

+# 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_