Curate · Engineering Reference

Lessons from building a browser-native AI IDE

This page is the project's engineering memory. It records why things are built the way they are, which tradeoffs were accepted, what pitfalls exist, and what a future maintainer should know before changing anything.

Primary agent

Claude Sonnet 4.6

Fast paths

Gemini pool + Haiku

Durable work

Inngest + Convex

Architecture Decisions

The system separates concerns by lifecycle: durable state, long-running work, browser runtime, and editor chrome each have a specific owner. Every decision here has a concrete tradeoff.

State is split by lifecycle

Decision: Convex owns durable state (projects, files, messages, binary storage, AI quotas). Zustand owns ephemeral state (tabs, active file, layout). CodeMirror owns transient keystroke-level state.
Why: Durable project data, local IDE UX, and transient editor transactions have vastly different lifecycles. Keystrokes cannot wait on backend round trips. Files cannot live only in memory.
Tradeoff: No dirty-buffer conflict model. Autosave is a 300ms debounce to Convex. Two users editing the same file would overwrite each other.
Evidence: convex/schema.ts, src/features/editor/store/use-editor-store.ts, src/features/editor/components/editor-view.tsx

Inngest owns all durable workflows

Decision: AI coding loops, GitHub imports, and GitHub exports are event-driven Inngest functions that mutate Convex through internal APIs using a shared secret key.
Why: These operations take seconds to minutes, must survive browser tab closures and serverless timeouts, and need cancellation and failure recovery hooks.
Tradeoff: Requires placeholder message rows, status fields, cancellation events, a 1-second DB sync wait, and a shared CURATE_CONVEX_INTERNAL_KEY. Leaking the key bypasses all Clerk auth.
Evidence: src/features/conversations/inngest/process-message.ts, src/features/projects/inngest/import-github-repo.ts, export-to-github.ts

WebContainers are a strictly managed singleton

Decision: One WebContainer per browser tab, enforced by module-level variables: webcontainerInstance, bootPromise, and cleanupPromise. Teardown waits for pending boot.
Why: SharedArrayBuffer constraints and browser memory limits make multiple containers unstable. An orphaned instance from premature teardown causes unrecoverable boot failures.
Tradeoff: The preview is a local sandbox, not a general VM. SSR frameworks, native modules, non-JS runtimes, and interactive terminal prompts are all unsupported.
Evidence: src/features/preview/hooks/use-webcontainer.ts, next.config.ts

Suggestions are editor extensions, not chat

Decision: Ghost text lives inside CodeMirror as a ViewPlugin, fires only on docChanged (actual typing), aborts stale requests, and accepts with Tab.
Why: Autocomplete should feel like editor infrastructure, not a conversational request loop. Triggering on cursor movement would burn API quota on every arrow key press.
Tradeoff: Suggestions are intentionally narrow (single insertion point) and cannot do multi-file reasoning. The 500ms debounce trades immediate response for quota efficiency.
Evidence: src/features/editor/extensions/suggestion/index.ts, src/features/editor/extensions/suggestion/fetcher.ts

Agent tools return recoverable errors

Decision: Tool handlers validate inputs with Zod, catch ArgumentValidationError, and return instructional error strings ('Call listFiles to get valid IDs') instead of throwing.
Why: Claude often guesses file paths instead of using Convex IDs. Returning a tool error string lets the agent self-correct in the next iteration rather than crashing the Inngest function.
Tradeoff: Errors become conversational artifacts in the context window, consuming tokens. Critical failures still need external monitoring. No structured error classes for post-mortem analysis.
Evidence: src/inngest/tools/read-file.ts, update-file.ts, delete-files.ts

GitHub sync is file-system aware

Decision: Import sorts folders by depth (parents before children), creates Convex nodes, and stores binaries via upload URLs. Export rebuilds full paths from the parentId chain, creates Git blobs, a single tree, and one commit.
Why: GitHub uses flat path-based trees. Curate uses recursive parentId nodes. Binary files need Convex storage, not text content. The translation must be explicit.
Tradeoff: This is import/export, not sync. No incremental updates, no branch selection (defaults to main/master), and individual file failures are logged but not surfaced to the user.
Evidence: src/features/projects/inngest/import-github-repo.ts, export-to-github.ts

AI Model Decisions

Model choice is treated as routing infrastructure. Each route optimizes for a different balance of cost, latency, and capability.

Suggestions use a distributed Gemini pool

Decision: Ghost text reserves a Gemini Flash model through a Convex mutation before each request. Five models with different RPM limits and weights form a pool. Selection is weighted random.
Why: Autocomplete is extremely high-frequency and latency-sensitive. The configured Gemini pool spreads requests across models with separate RPM limits. Random selection avoids the write contention a round-robin counter would cause.
Tradeoff: The 95% safety margin is conservative. The prompt must stay narrow and schema-bound (Zod). Parsing failures silently return empty strings, protecting typing flow but hiding failures.
Evidence: src/app/api/suggestion/route.ts, convex/GeminiAi.ts, src/lib/ai-models.ts

Quick edit routes by selection size

Decision: Selections ≥1500 characters use Claude Sonnet. Smaller selections use Claude Haiku.
Why: Small edits benefit from low latency and cost. Large edits need stronger context preservation and code reasoning to avoid mangling surrounding code.
Tradeoff: The 1500-char threshold is a pragmatic heuristic. It ignores language, semantic complexity, and task difficulty. Needs telemetry before it can become more sophisticated.
Evidence: src/app/api/quick-edit/route.ts

The coding agent defaults to Sonnet

Decision: AgentKit uses Claude Sonnet 4.6 with temperature 0.2, 8000 max output tokens, and maxIter 5. Opus exists in constants but has no active route.
Why: Sonnet is the balanced coding model: good tool use, good code generation, without the cost and latency of Opus. Five iterations is sufficient for most multi-step file modifications.
Tradeoff: Opus is reserved capacity for future deep reasoning escalation, not current behavior. Activating it needs a deliberate route, trigger, and budget guardrails.
Evidence: src/features/conversations/inngest/process-message.ts, src/lib/ai-models.ts

Claude routes are not provider-abstract

Decision: The agent prompt, XML structure, tool-call handling, and router logic are all tuned for Claude behavior — specifically that Anthropic responses can contain text and tool calls in the same step.
Why: The router checks hasTextResponse && !hasToolCalls to decide when to stop. This is Claude-specific behavior. OpenAI models handle tool calls differently.
Tradeoff: Adding OpenAI as a runtime AI provider should be treated as a new route with its own prompts, stopping rules, and quality checks — not a drop-in model swap.
Evidence: src/features/conversations/inngest/process-message.ts, constants.ts

Active Model Inventory

Complete routing table. OpenAI SDKs exist in the repo for tool metadata, but all runtime AI routes use Anthropic or Google.

Suggestion primary

5 models

When: Convex reservation (weighted random)

Why: Configured for high request capacity across the suggestion pool

Tradeoff: Prompt must stay schema-bound. No deep reasoning.

gemini-3.5-flash, gemini-2.5-flash-lite, gemini-2.5-flash, gemini-2.0-flash, gemini-2.0-flash-lite

Suggestion fallback

claude-haiku-4-5-20251001

When: All Gemini quotas exhausted (95% safety margin)

Why: Different provider = independent quota before the UI reports exhaustion.

Tradeoff: More expensive per-request than Gemini. Should be rare.

Small quick edit + Titles

claude-haiku-4-5-20251001

When: Selection < 1500 chars / Title generation

Why: Fast, cheap. Small edits and titles don't need heavy reasoning.

Tradeoff: Not suitable for large rewrites or multi-step reasoning.

Large quick edit + Coding agent

claude-sonnet-4-6

When: Selection ≥ 1500 chars / Agent invocation

Why: Best balance of tool use, code quality, cost, and latency.

Tradeoff: Higher cost than Haiku. 8000 token output limit.

Reserved

claude-opus-4-8

When: None (configured, not routed)

Why: Future deep reasoning escalation tier.

Tradeoff: Needs deliberate route, trigger, and budget guardrails before activation.

Technology Choices

Why each major technology was selected, what alternatives were considered, and why they were rejected.

Convex

Real-time database, file storage, auth, AI quota management

Why chosen

Reactive queries auto-update the UI. Built-in binary storage. Mutations work as distributed locks (rate limiting). Typed schemas with validation.

Alternative: Supabase / PlanetScale + S3

Would require rebuilding the real-time query layer, binary storage boundary, and generated type workflow that Convex currently provides in one system.

Inngest

Durable background workflows (AI agent, GitHub sync)

Why chosen

Event-driven. Survives serverless timeouts. Built-in cancelOn, onFailure, step-based orchestration. Works with AgentKit for AI agent loops.

Alternative: Temporal / BullMQ / Trigger.dev

Would require rewriting the current event names, cancelOn behavior, onFailure hooks, and AgentKit workflow integration already built around Inngest.

WebContainers

Browser-local Node.js runtime for live preview

Why chosen

Zero-install, zero-infra. Users get a real dev server without any backend sandbox. Secure by default (WASM sandbox, no host access).

Alternative: CodeSandbox API / Stackblitz SDK / VM-based sandbox

Would move preview execution out of Curate's browser-local lifecycle and require a different file-sync, security, and provisioning model.

CodeMirror 6

Code editor with custom extensions

Why chosen

Extension architecture allows ghost text, quick edit popover, and custom themes as first-class features. No wrapper library needed.

Alternative: Monaco Editor

The current ghost text, quick edit, selection tooltip, minimap, and theme work are implemented as CodeMirror extensions; switching would be a rewrite.

Clerk

Authentication (OAuth, session management)

Why chosen

Handles OAuth providers, session tokens, and integrates directly with both Next.js middleware and Convex identity verification.

Alternative: NextAuth / Auth0

The current auth boundary depends on Clerk middleware, Clerk OAuth tokens, and Convex identity verification; replacing it would affect every protected route and GitHub workflow.

Reliability Patterns

Most Curate failures come from async work, model tool use, or browser runtime lifecycle. These patterns keep failures recoverable.

Cancel and bound all model work

The agent loop is bounded at maxIter: 5. New chat messages and stop-button clicks send message/cancel events. The Inngest cancelOn condition matches messageId, so only the correct in-progress function is terminated.

process-message.ts (cancelOn, maxIter), src/app/api/messages/cancel/route.ts

Pre-validate destructive operations

deleteFiles validates every file ID exists before deleting anything. This prevents mixed valid/invalid partial deletes that would leave the file tree in an inconsistent state.

src/inngest/tools/delete-files.ts

Keep preview lifecycle idempotent

Boot waits for cleanup. Teardown waits for boot. Import pauses startup. File sync runs regardless of container status (not gated on 'running'). Terminal output appends only new bytes.

use-webcontainer.ts, preview-terminal.tsx

Ghost text must not fire on cursor movement

The suggestion plugin triggers only on docChanged, never on selectionSet. Combined with the AbortController on each new request, stale suggestions from previous positions are automatically cancelled.

src/features/editor/extensions/suggestion/index.ts

Bound external documentation context

Quick edit accepts at most 3 URLs, races each scrape against a 5-second timeout (Firecrawl can hang), trims docs to 3000 chars, and slices large file context to 15000 chars (keeping top and bottom halves for imports/exports visibility).

src/app/api/quick-edit/route.ts

Cross-origin isolation is the preview tax

COEP (credentialless) and COOP (same-origin) headers are applied globally so SharedArrayBuffer works for WebContainers. Scoping to /projects/* only would be safer but isn't implemented.

next.config.ts

Wait for eventual consistency

The agent function sleeps 1 second after receiving the message event before querying conversation history. This handles the gap between Convex write and read replica sync.

process-message.ts (step.sleep 'wait-for-db-sync')

Common Pitfalls

Known failure modes that have been encountered and solved (or mitigated). Check here before debugging an unfamiliar issue.

"Only a single WebContainer instance" crash

Symptom: Preview fails to boot after navigation or hot reload.
Cause: Previous instance wasn't torn down before new boot. Can happen if teardown is called during pending boot without awaiting it.
Fix: The cleanupPromise pattern handles this. If the error still occurs, the restart button falls back to window.location.reload().; use-webcontainer.ts (teardownWebContainer, restart callback)

Agent passes file paths instead of Convex IDs

Symptom: Tool calls fail with ArgumentValidationError.
Cause: Claude guesses paths like 'src/App.jsx' instead of calling listFiles first to get the actual Convex document ID.
Fix: Tools return an instructional error string telling the agent to call listFiles. The system prompt rule explicitly says: 'NEVER use file paths as IDs.'; process-message.ts (system prompt), read-file.ts

Suggestion quota exhaustion cascade

Symptom: Ghost text stops appearing for all users.
Cause: All 5 Gemini models hit their 95% safety margin within the same 60-second window.
Fix: The API route catches the Convex error and falls back to Claude Haiku. If Haiku also 429s, returns empty string with 429 status.; suggestion/route.ts (triple error handling)

GitHub import silently skips files

Symptom: Imported project is missing some files.
Cause: Individual file fetches in the import loop catch and log errors but continue. No user-facing report of skipped files.
Fix: Known limitation. The error is logged server-side. Surfacing a per-file skip report to the user is a roadmap item.; import-github-repo.ts (catch block in create-files step)

Things Future Maintainers Should Not Accidentally Break

Code that looks simple but has non-obvious reasons for existing. Do not change without understanding the context.

WebContainer singleton pattern and cleanupPromise

Do not make webcontainerInstance, bootPromise, or cleanupPromise local to the hook. They must be module-level to survive React re-renders and enforce the singleton.

Making them useRef or useState variables would break the singleton guarantee across component remounts. cleanupPromise ensures teardowns wait for pending boots.

COEP/COOP headers in next.config.ts

Removing these headers will silently break WebContainer boot. SharedArrayBuffer will throw without cross-origin isolation.

The headers are global (/:path*). Scoping to /projects/* only would be better security but hasn't been tested with Clerk's iframe requirements.

cancelOn event matching in process-message

The if condition 'event.data.messageId == async.data.messageId' is Inngest expression syntax, not JavaScript. Do not refactor it.

This matches the incoming cancel event's messageId against the original trigger event's messageId to cancel only the correct function instance.

The 1-second DB sync sleep

The step.sleep('wait-for-db-sync', '1s') in process-message is not arbitrary. Removing it causes the agent to sometimes miss the user's message in conversation history.

Convex mutations propagate to read replicas with eventual consistency. The sleep bridges this gap.

Random vs. round-robin in GeminiAi.ts

Do not replace Math.random() with a counter-based round-robin. A counter would require a dedicated Convex row updated on every keystroke across all users.

The comment in the code explains why a shared round-robin counter would add write contention on every keystroke. Weighted random selection avoids that shared counter.

System prompt XML structure

The <identity>, <environment>, <tools>, <rules>, <workflow> XML tags are not cosmetic. Claude models are fine-tuned to parse XML-structured system prompts with higher fidelity than markdown.

Switching to markdown headers would likely degrade tool-use accuracy and rule adherence.

File synchronization behavior

The useEffect for file sync deliberately omits 'status' from its dependency array. Do not add it back.

Syncing only when status === 'running' would lose edits made during the install/boot phase. This was a deliberate improvement.

Convex vs Zustand ownership boundaries

Do not move open tabs or cursor position state into Convex. Do not move durable file data into Zustand.

Backend round trips are too slow for transient editor state. Zustand is wiped on refresh, which is fatal for project files.

docChanged-only suggestion triggering

Do not trigger AI suggestions on 'selectionSet' (cursor movement). Only trigger on 'docChanged' (actual typing).

Triggering on cursor movement would burn through API quotas instantly as users navigate files.

ArgumentValidationError recovery patterns

AgentKit tools must catch ArgumentValidationError and return instructional strings (e.g., 'Use listFiles') instead of throwing.

Models frequently hallucinate file paths instead of Convex IDs. Throwing crashes the Inngest function; returning strings lets the model self-correct.

import/export ordering requirements

GitHub import must sort folders by depth (parents before children). GitHub export must recursively rebuild string paths from parentIds.

Convex uses a recursive tree. GitHub uses flat paths. Failing to sort by depth causes parent constraint violations during import.

Agent loop maxIter limits

Do not remove or arbitrarily increase the 'maxIter: 5' limit in the Inngest process-message workflow.

Unbounded tool-calling loops can consume large token budgets quickly. The current implementation treats 5 iterations as the intended cap for this toolset.

Gemini safety margin logic

Do not remove the 95% safety margin check (SAFETY_FACTOR = 0.95) when reserving Gemini models in Convex.

Reserving exactly 100% of the quota causes API rate limits during concurrent typing due to the delay between reservation and execution.

Future Improvements

Cleanup targets and planned enhancements. These represent known limitations, not bugs.

Telemetry-driven model routing

Model thresholds (1500 chars, maxIter 5, 95% safety margin) are all hard-coded. No runtime telemetry for latency, quality, or cost by route. Adding observability would enable data-driven tuning.

User-facing import error report

GitHub import logs file-level failures but doesn't surface them to the user. A post-import summary showing skipped files and reasons would improve trust.

Structured agent tool errors

Agent tools return plain strings for errors. Structured error classes with codes would enable better post-failure analysis and automated retry strategies.

Scoped COEP/COOP headers

Cross-origin isolation headers are applied globally. Scoping to /projects/* would reduce security surface for public pages.

Collaborative editing

Currently no conflict resolution for concurrent edits. Convex's real-time primitives could support a CRDT or OT layer, but the 300ms debounce autosave would need to be rearchitected.

Go back to home

Curate · Engineering Reference

Lessons from building a browser-native AI IDE

Primary agent

Claude Sonnet 4.6

Fast paths

Gemini pool + Haiku

Durable work

Inngest + Convex

Architecture Decisions

The system separates concerns by lifecycle: durable state, long-running work, browser runtime, and editor chrome each have a specific owner. Every decision here has a concrete tradeoff.

State is split by lifecycle

Decision: Convex owns durable state (projects, files, messages, binary storage, AI quotas). Zustand owns ephemeral state (tabs, active file, layout). CodeMirror owns transient keystroke-level state.
Why: Durable project data, local IDE UX, and transient editor transactions have vastly different lifecycles. Keystrokes cannot wait on backend round trips. Files cannot live only in memory.
Tradeoff: No dirty-buffer conflict model. Autosave is a 300ms debounce to Convex. Two users editing the same file would overwrite each other.
Evidence: convex/schema.ts, src/features/editor/store/use-editor-store.ts, src/features/editor/components/editor-view.tsx

Inngest owns all durable workflows

Decision: AI coding loops, GitHub imports, and GitHub exports are event-driven Inngest functions that mutate Convex through internal APIs using a shared secret key.
Why: These operations take seconds to minutes, must survive browser tab closures and serverless timeouts, and need cancellation and failure recovery hooks.
Tradeoff: Requires placeholder message rows, status fields, cancellation events, a 1-second DB sync wait, and a shared CURATE_CONVEX_INTERNAL_KEY. Leaking the key bypasses all Clerk auth.
Evidence: src/features/conversations/inngest/process-message.ts, src/features/projects/inngest/import-github-repo.ts, export-to-github.ts

WebContainers are a strictly managed singleton

Decision: One WebContainer per browser tab, enforced by module-level variables: webcontainerInstance, bootPromise, and cleanupPromise. Teardown waits for pending boot.
Why: SharedArrayBuffer constraints and browser memory limits make multiple containers unstable. An orphaned instance from premature teardown causes unrecoverable boot failures.
Tradeoff: The preview is a local sandbox, not a general VM. SSR frameworks, native modules, non-JS runtimes, and interactive terminal prompts are all unsupported.
Evidence: src/features/preview/hooks/use-webcontainer.ts, next.config.ts

Suggestions are editor extensions, not chat

Decision: Ghost text lives inside CodeMirror as a ViewPlugin, fires only on docChanged (actual typing), aborts stale requests, and accepts with Tab.
Why: Autocomplete should feel like editor infrastructure, not a conversational request loop. Triggering on cursor movement would burn API quota on every arrow key press.
Tradeoff: Suggestions are intentionally narrow (single insertion point) and cannot do multi-file reasoning. The 500ms debounce trades immediate response for quota efficiency.
Evidence: src/features/editor/extensions/suggestion/index.ts, src/features/editor/extensions/suggestion/fetcher.ts

Agent tools return recoverable errors

Decision: Tool handlers validate inputs with Zod, catch ArgumentValidationError, and return instructional error strings ('Call listFiles to get valid IDs') instead of throwing.
Why: Claude often guesses file paths instead of using Convex IDs. Returning a tool error string lets the agent self-correct in the next iteration rather than crashing the Inngest function.
Tradeoff: Errors become conversational artifacts in the context window, consuming tokens. Critical failures still need external monitoring. No structured error classes for post-mortem analysis.
Evidence: src/inngest/tools/read-file.ts, update-file.ts, delete-files.ts

GitHub sync is file-system aware

Decision: Import sorts folders by depth (parents before children), creates Convex nodes, and stores binaries via upload URLs. Export rebuilds full paths from the parentId chain, creates Git blobs, a single tree, and one commit.
Why: GitHub uses flat path-based trees. Curate uses recursive parentId nodes. Binary files need Convex storage, not text content. The translation must be explicit.
Tradeoff: This is import/export, not sync. No incremental updates, no branch selection (defaults to main/master), and individual file failures are logged but not surfaced to the user.
Evidence: src/features/projects/inngest/import-github-repo.ts, export-to-github.ts

AI Model Decisions

Model choice is treated as routing infrastructure. Each route optimizes for a different balance of cost, latency, and capability.

Suggestions use a distributed Gemini pool

Decision: Ghost text reserves a Gemini Flash model through a Convex mutation before each request. Five models with different RPM limits and weights form a pool. Selection is weighted random.
Why: Autocomplete is extremely high-frequency and latency-sensitive. The configured Gemini pool spreads requests across models with separate RPM limits. Random selection avoids the write contention a round-robin counter would cause.
Tradeoff: The 95% safety margin is conservative. The prompt must stay narrow and schema-bound (Zod). Parsing failures silently return empty strings, protecting typing flow but hiding failures.
Evidence: src/app/api/suggestion/route.ts, convex/GeminiAi.ts, src/lib/ai-models.ts

Quick edit routes by selection size

Decision: Selections ≥1500 characters use Claude Sonnet. Smaller selections use Claude Haiku.
Why: Small edits benefit from low latency and cost. Large edits need stronger context preservation and code reasoning to avoid mangling surrounding code.
Tradeoff: The 1500-char threshold is a pragmatic heuristic. It ignores language, semantic complexity, and task difficulty. Needs telemetry before it can become more sophisticated.
Evidence: src/app/api/quick-edit/route.ts

The coding agent defaults to Sonnet

Decision: AgentKit uses Claude Sonnet 4.6 with temperature 0.2, 8000 max output tokens, and maxIter 5. Opus exists in constants but has no active route.
Why: Sonnet is the balanced coding model: good tool use, good code generation, without the cost and latency of Opus. Five iterations is sufficient for most multi-step file modifications.
Tradeoff: Opus is reserved capacity for future deep reasoning escalation, not current behavior. Activating it needs a deliberate route, trigger, and budget guardrails.
Evidence: src/features/conversations/inngest/process-message.ts, src/lib/ai-models.ts

Claude routes are not provider-abstract

Decision: The agent prompt, XML structure, tool-call handling, and router logic are all tuned for Claude behavior — specifically that Anthropic responses can contain text and tool calls in the same step.
Why: The router checks hasTextResponse && !hasToolCalls to decide when to stop. This is Claude-specific behavior. OpenAI models handle tool calls differently.
Tradeoff: Adding OpenAI as a runtime AI provider should be treated as a new route with its own prompts, stopping rules, and quality checks — not a drop-in model swap.
Evidence: src/features/conversations/inngest/process-message.ts, constants.ts

Active Model Inventory

Complete routing table. OpenAI SDKs exist in the repo for tool metadata, but all runtime AI routes use Anthropic or Google.

Suggestion primary

5 models

When: Convex reservation (weighted random)

Why: Configured for high request capacity across the suggestion pool

Tradeoff: Prompt must stay schema-bound. No deep reasoning.

gemini-3.5-flash, gemini-2.5-flash-lite, gemini-2.5-flash, gemini-2.0-flash, gemini-2.0-flash-lite

Suggestion fallback

claude-haiku-4-5-20251001

When: All Gemini quotas exhausted (95% safety margin)

Why: Different provider = independent quota before the UI reports exhaustion.

Tradeoff: More expensive per-request than Gemini. Should be rare.

Small quick edit + Titles

claude-haiku-4-5-20251001

When: Selection < 1500 chars / Title generation

Why: Fast, cheap. Small edits and titles don't need heavy reasoning.

Tradeoff: Not suitable for large rewrites or multi-step reasoning.

Large quick edit + Coding agent

claude-sonnet-4-6

When: Selection ≥ 1500 chars / Agent invocation

Why: Best balance of tool use, code quality, cost, and latency.

Tradeoff: Higher cost than Haiku. 8000 token output limit.

Reserved

claude-opus-4-8

When: None (configured, not routed)

Why: Future deep reasoning escalation tier.

Tradeoff: Needs deliberate route, trigger, and budget guardrails before activation.

Technology Choices

Why each major technology was selected, what alternatives were considered, and why they were rejected.

Convex

Real-time database, file storage, auth, AI quota management

Why chosen

Reactive queries auto-update the UI. Built-in binary storage. Mutations work as distributed locks (rate limiting). Typed schemas with validation.

Alternative: Supabase / PlanetScale + S3

Would require rebuilding the real-time query layer, binary storage boundary, and generated type workflow that Convex currently provides in one system.

Inngest

Durable background workflows (AI agent, GitHub sync)

Why chosen

Event-driven. Survives serverless timeouts. Built-in cancelOn, onFailure, step-based orchestration. Works with AgentKit for AI agent loops.

Alternative: Temporal / BullMQ / Trigger.dev

Would require rewriting the current event names, cancelOn behavior, onFailure hooks, and AgentKit workflow integration already built around Inngest.

WebContainers

Browser-local Node.js runtime for live preview

Why chosen

Zero-install, zero-infra. Users get a real dev server without any backend sandbox. Secure by default (WASM sandbox, no host access).

Alternative: CodeSandbox API / Stackblitz SDK / VM-based sandbox

Would move preview execution out of Curate's browser-local lifecycle and require a different file-sync, security, and provisioning model.

CodeMirror 6

Code editor with custom extensions

Why chosen

Extension architecture allows ghost text, quick edit popover, and custom themes as first-class features. No wrapper library needed.

Alternative: Monaco Editor

The current ghost text, quick edit, selection tooltip, minimap, and theme work are implemented as CodeMirror extensions; switching would be a rewrite.

Clerk

Authentication (OAuth, session management)

Why chosen

Handles OAuth providers, session tokens, and integrates directly with both Next.js middleware and Convex identity verification.

Alternative: NextAuth / Auth0

The current auth boundary depends on Clerk middleware, Clerk OAuth tokens, and Convex identity verification; replacing it would affect every protected route and GitHub workflow.

Reliability Patterns

Most Curate failures come from async work, model tool use, or browser runtime lifecycle. These patterns keep failures recoverable.

Cancel and bound all model work

process-message.ts (cancelOn, maxIter), src/app/api/messages/cancel/route.ts

Pre-validate destructive operations

deleteFiles validates every file ID exists before deleting anything. This prevents mixed valid/invalid partial deletes that would leave the file tree in an inconsistent state.

src/inngest/tools/delete-files.ts

Keep preview lifecycle idempotent

Boot waits for cleanup. Teardown waits for boot. Import pauses startup. File sync runs regardless of container status (not gated on 'running'). Terminal output appends only new bytes.

use-webcontainer.ts, preview-terminal.tsx

Ghost text must not fire on cursor movement

The suggestion plugin triggers only on docChanged, never on selectionSet. Combined with the AbortController on each new request, stale suggestions from previous positions are automatically cancelled.

src/features/editor/extensions/suggestion/index.ts

Bound external documentation context

src/app/api/quick-edit/route.ts

Cross-origin isolation is the preview tax

COEP (credentialless) and COOP (same-origin) headers are applied globally so SharedArrayBuffer works for WebContainers. Scoping to /projects/* only would be safer but isn't implemented.

next.config.ts

Wait for eventual consistency

The agent function sleeps 1 second after receiving the message event before querying conversation history. This handles the gap between Convex write and read replica sync.

process-message.ts (step.sleep 'wait-for-db-sync')

Common Pitfalls

Known failure modes that have been encountered and solved (or mitigated). Check here before debugging an unfamiliar issue.

"Only a single WebContainer instance" crash

Symptom: Preview fails to boot after navigation or hot reload.
Cause: Previous instance wasn't torn down before new boot. Can happen if teardown is called during pending boot without awaiting it.
Fix: The cleanupPromise pattern handles this. If the error still occurs, the restart button falls back to window.location.reload().; use-webcontainer.ts (teardownWebContainer, restart callback)

Agent passes file paths instead of Convex IDs

Symptom: Tool calls fail with ArgumentValidationError.
Cause: Claude guesses paths like 'src/App.jsx' instead of calling listFiles first to get the actual Convex document ID.
Fix: Tools return an instructional error string telling the agent to call listFiles. The system prompt rule explicitly says: 'NEVER use file paths as IDs.'; process-message.ts (system prompt), read-file.ts

Suggestion quota exhaustion cascade

Symptom: Ghost text stops appearing for all users.
Cause: All 5 Gemini models hit their 95% safety margin within the same 60-second window.
Fix: The API route catches the Convex error and falls back to Claude Haiku. If Haiku also 429s, returns empty string with 429 status.; suggestion/route.ts (triple error handling)

GitHub import silently skips files

Symptom: Imported project is missing some files.
Cause: Individual file fetches in the import loop catch and log errors but continue. No user-facing report of skipped files.
Fix: Known limitation. The error is logged server-side. Surfacing a per-file skip report to the user is a roadmap item.; import-github-repo.ts (catch block in create-files step)

Things Future Maintainers Should Not Accidentally Break

Code that looks simple but has non-obvious reasons for existing. Do not change without understanding the context.

WebContainer singleton pattern and cleanupPromise

Do not make webcontainerInstance, bootPromise, or cleanupPromise local to the hook. They must be module-level to survive React re-renders and enforce the singleton.

Making them useRef or useState variables would break the singleton guarantee across component remounts. cleanupPromise ensures teardowns wait for pending boots.

COEP/COOP headers in next.config.ts

Removing these headers will silently break WebContainer boot. SharedArrayBuffer will throw without cross-origin isolation.

The headers are global (/:path*). Scoping to /projects/* only would be better security but hasn't been tested with Clerk's iframe requirements.

cancelOn event matching in process-message

The if condition 'event.data.messageId == async.data.messageId' is Inngest expression syntax, not JavaScript. Do not refactor it.

This matches the incoming cancel event's messageId against the original trigger event's messageId to cancel only the correct function instance.

The 1-second DB sync sleep

The step.sleep('wait-for-db-sync', '1s') in process-message is not arbitrary. Removing it causes the agent to sometimes miss the user's message in conversation history.

Convex mutations propagate to read replicas with eventual consistency. The sleep bridges this gap.

Random vs. round-robin in GeminiAi.ts

Do not replace Math.random() with a counter-based round-robin. A counter would require a dedicated Convex row updated on every keystroke across all users.

The comment in the code explains why a shared round-robin counter would add write contention on every keystroke. Weighted random selection avoids that shared counter.

System prompt XML structure

The <identity>, <environment>, <tools>, <rules>, <workflow> XML tags are not cosmetic. Claude models are fine-tuned to parse XML-structured system prompts with higher fidelity than markdown.

Switching to markdown headers would likely degrade tool-use accuracy and rule adherence.

File synchronization behavior

The useEffect for file sync deliberately omits 'status' from its dependency array. Do not add it back.

Syncing only when status === 'running' would lose edits made during the install/boot phase. This was a deliberate improvement.

Convex vs Zustand ownership boundaries

Do not move open tabs or cursor position state into Convex. Do not move durable file data into Zustand.

Backend round trips are too slow for transient editor state. Zustand is wiped on refresh, which is fatal for project files.

docChanged-only suggestion triggering

Do not trigger AI suggestions on 'selectionSet' (cursor movement). Only trigger on 'docChanged' (actual typing).

Triggering on cursor movement would burn through API quotas instantly as users navigate files.

ArgumentValidationError recovery patterns

AgentKit tools must catch ArgumentValidationError and return instructional strings (e.g., 'Use listFiles') instead of throwing.

Models frequently hallucinate file paths instead of Convex IDs. Throwing crashes the Inngest function; returning strings lets the model self-correct.

import/export ordering requirements

GitHub import must sort folders by depth (parents before children). GitHub export must recursively rebuild string paths from parentIds.

Convex uses a recursive tree. GitHub uses flat paths. Failing to sort by depth causes parent constraint violations during import.

Agent loop maxIter limits

Do not remove or arbitrarily increase the 'maxIter: 5' limit in the Inngest process-message workflow.

Unbounded tool-calling loops can consume large token budgets quickly. The current implementation treats 5 iterations as the intended cap for this toolset.

Gemini safety margin logic

Do not remove the 95% safety margin check (SAFETY_FACTOR = 0.95) when reserving Gemini models in Convex.

Reserving exactly 100% of the quota causes API rate limits during concurrent typing due to the delay between reservation and execution.

Future Improvements

Cleanup targets and planned enhancements. These represent known limitations, not bugs.

Telemetry-driven model routing

Model thresholds (1500 chars, maxIter 5, 95% safety margin) are all hard-coded. No runtime telemetry for latency, quality, or cost by route. Adding observability would enable data-driven tuning.

User-facing import error report

GitHub import logs file-level failures but doesn't surface them to the user. A post-import summary showing skipped files and reasons would improve trust.

Structured agent tool errors

Agent tools return plain strings for errors. Structured error classes with codes would enable better post-failure analysis and automated retry strategies.

Scoped COEP/COOP headers

Cross-origin isolation headers are applied globally. Scoping to /projects/* would reduce security surface for public pages.

Collaborative editing

Currently no conflict resolution for concurrent edits. Convex's real-time primitives could support a CRDT or OT layer, but the 300ms debounce autosave would need to be rearchitected.

Go back to home

Lessons from building a browser-native AI IDE

Architecture Decisions

State is split by lifecycle

Inngest owns all durable workflows

WebContainers are a strictly managed singleton

Suggestions are editor extensions, not chat

Agent tools return recoverable errors

GitHub sync is file-system aware

AI Model Decisions

Suggestions use a distributed Gemini pool

Quick edit routes by selection size

The coding agent defaults to Sonnet

Claude routes are not provider-abstract

Active Model Inventory

Suggestion primary

Suggestion fallback

Small quick edit + Titles

Large quick edit + Coding agent

Reserved

Technology Choices

Convex

Inngest

WebContainers

CodeMirror 6

Clerk

Reliability Patterns

Cancel and bound all model work

Pre-validate destructive operations

Keep preview lifecycle idempotent

Ghost text must not fire on cursor movement

Bound external documentation context

Cross-origin isolation is the preview tax

Wait for eventual consistency

Common Pitfalls

"Only a single WebContainer instance" crash

Agent passes file paths instead of Convex IDs

Suggestion quota exhaustion cascade

GitHub import silently skips files

Things Future Maintainers Should Not Accidentally Break

WebContainer singleton pattern and cleanupPromise

COEP/COOP headers in next.config.ts

cancelOn event matching in process-message

The 1-second DB sync sleep

Random vs. round-robin in GeminiAi.ts

System prompt XML structure

File synchronization behavior

Convex vs Zustand ownership boundaries

docChanged-only suggestion triggering

ArgumentValidationError recovery patterns

import/export ordering requirements

Agent loop maxIter limits

Gemini safety margin logic

Future Improvements

Telemetry-driven model routing

User-facing import error report

Structured agent tool errors

Scoped COEP/COOP headers

Collaborative editing

Preparing workspace

Lessons from building a browser-native AI IDE

Architecture Decisions

State is split by lifecycle

Inngest owns all durable workflows

WebContainers are a strictly managed singleton

Suggestions are editor extensions, not chat

Agent tools return recoverable errors

GitHub sync is file-system aware

AI Model Decisions

Suggestions use a distributed Gemini pool

Quick edit routes by selection size

The coding agent defaults to Sonnet

Claude routes are not provider-abstract

Active Model Inventory

Suggestion primary

Suggestion fallback

Small quick edit + Titles

Large quick edit + Coding agent

Reserved

Technology Choices

Convex