Convex Backend

The Convex backend handles all server-side logic, database operations, and AI interactions.

Database Schema

The application uses four main tables:

Files Table

Stores uploaded document metadata:

files: defineTable({
  name: v.string(),
  storageId: v.id('_storage'),
  type: v.string(),
  size: v.number(),
})

Chunks Table

Stores document chunks with embeddings:

chunks: defineTable({
  fileId: v.id('files'),
  text: v.string(),
  embedding: v.array(v.float64()),
})

Threads Table

Stores chat conversations:

threads: defineTable({
  // Agent framework managed
})

Messages Table

Stores individual chat messages:

messages: defineTable({
  threadId: v.id("threads"),
  role: v.string(),
  content: v.string(),
  sources: v.optional(v.array(...)),
})

Key Functions

Queries

• files.list - Get all uploaded files
• chat.getThread - Get a thread with messages

Mutations

• files.upload - Handle file upload
• files.remove - Delete a file and its chunks
• chat.send - Send a user message

Actions

• indexing.indexFile - Process and index a file
• agent.chat - Run the AI agent for a response

Vector Search

The app uses Convex's built-in vector search:

const results = await ctx.vectorSearch('chunks', 'by_embedding', {
  vector: queryEmbedding,
  limit: 5,
})

This finds the most semantically similar chunks to the user's question.