Convex Backend

Convex Backend

Overview

Convex is the sole backend — no Express, no custom server. All state, business logic, and external API calls run through Convex functions. The frontend connects via real-time subscriptions.

Schema

Four tables in convex/schema.ts:

Investigation Status Flow

planning → investigating → analyzing → complete
                                     → failed

Indexes

• findings.by_investigation → ["investigationId"]
• steps.by_investigation → ["investigationId"]
• graph_edges.by_investigation → ["investigationId"]

Function Types

Public vs Internal

• Public (action, mutation, query): Callable from frontend via api.*
• Internal (internalAction, internalMutation): Only callable from other Convex functions via internal.*

Most tool implementations (convex/tools/*.ts) use internalAction — they're only called by the orchestrator, never directly from the frontend.

Key Patterns

Creating an investigation

// convex/investigations.ts — create mutation
const id = await ctx.db.insert("investigations", {
  query: `Investigate ${args.targetName}`,
  targetName: args.targetName,
  targetDescription: args.targetDescription,
  targetPhone: args.targetPhone,
  targetPhoto: args.targetPhoto,
  knownLinks: args.knownLinks,
  extremeMode: args.extremeMode ?? false,
  status: "planning",
  stepCount: 0,
  createdAt: Date.now(),
});

Querying with indexes

// Always use .withIndex() for FK lookups
const findings = await ctx.db
  .query("findings")
  .withIndex("by_investigation", (q) =>
    q.eq("investigationId", args.investigationId)
  )
  .order("desc")
  .collect();

Scheduling next step (self-chaining)

// convex/orchestrator.ts — chains via scheduler
await ctx.scheduler.runAfter(0, internal.orchestrator.step, {
  investigationId: args.investigationId,
  conversationHistory: JSON.stringify(finalHistory),
  consecutiveSaveOnlySteps: consecutiveSaveOnly,
  maigretAvailable,
  extremeMode,
});

This avoids the 10-minute Convex action timeout by splitting each step into its own action invocation.

Actions calling mutations

// Inside an action handler
await ctx.runMutation(api.investigations.updateStatus, {
  id: args.investigationId,
  status: "investigating",
});

File uploads

// Generate upload URL for photos
export const generateUploadUrl = mutation({
  handler: async (ctx) => {
    return await ctx.storage.generateUploadUrl();
  },
});

File Map

Environment Variables

Set in Convex dashboard (Settings → Environment Variables), NOT in .env:

• ANTHROPIC_API_KEY — Claude API for orchestrator
• BROWSER_USE_API_KEY — Browser Use Cloud
• BRAVE_API_KEY — Brave Search API (fast web lookups)
• PICARTA_API_KEY — Picarta AI geolocation
• INTELX_API_KEY — Intelligence X dark web search (extreme mode)
• SERPAPI_API_KEY — SerpAPI for reverse image search
• MAIGRET_SIDECAR_URL — Maigret sidecar URL (optional, defaults to http://localhost:8000)

Gotchas

• No fetch in mutations/queries — Only actions can make HTTP requests
• 10-minute timeout — Actions auto-terminate. Use scheduler.runAfter(0, ...) to chain long-running workflows
• Convex IDs are typed — Use v.id("tableName"), not v.string() for foreign keys
• No raw SQL — Use .query() builder with .withIndex(), .filter(), .order()
• Conversation history is serialized — Stored as JSON string since Convex doesn't support deeply nested dynamic objects in validators
• Batch mutations — addSteps and addEdges accept arrays and insert in a loop with shared timestamp, reducing round trips