Architecture

​

Overview

1. Convex backend - The core database and function runtime
2. Convex dashboard - Web UI for managing deployments
3. Your frontend app - Hosted on your platform of choice (Vercel, Netlify, etc.)

​

Core components

​

Convex backend

• Database layer - Stores and queries your data with strong consistency
• Function runtime - Executes your TypeScript queries, mutations, and actions
• Sync engine - Powers real-time reactivity and live updates
• HTTP server - Serves API endpoints and handles client connections

​

Key services

​

Dashboard

• Viewing and editing data in your tables
• Monitoring function executions and logs
• Running ad-hoc queries and mutations
• Managing deployments and configurations
• Exploring your database schema

​

Client libraries

• React - Hooks for queries, mutations, and real-time updates
• Next.js - Server and client components support
• Vue, Svelte - Framework-specific integrations
• Node.js - Server-side client for backend-to-backend communication

​

Repository structure

​

Rust crates (crates/)

• local_backend/ - Application server and serving edge
• database/ - Core database implementation
• sync/ - Real-time synchronization engine
• vector/ - Vector search capabilities
• text_search/ - Full-text search implementation
• function_runner/ - JavaScript function execution runtime
• storage/ - Storage abstraction layer

​

TypeScript packages (npm-packages/)

• convex/ - Main client library published to npm
• udf-runtime/ - JavaScript environment for user-defined functions
• system-udfs/ - System functions used by the CLI and dashboard
• dashboard/ - Cloud-hosted dashboard
• dashboard-self-hosted/ - Self-hosted dashboard build
• dashboard-common/ - Shared dashboard code

​

Data flow

import { useQuery } from "convex/react";
import { api } from "./convex/_generated/api";

function MyComponent() {
  const messages = useQuery(api.messages.list);
  // Component automatically re-renders when data changes
}

import { query } from "./_generated/server";

export const list = query({
  args: {},
  handler: async (ctx) => {
    // Strong consistency - always reads the latest data
    return await ctx.db.query("messages").collect();
  },
});

​

Function types

​

Queries

• Read-only - Cannot modify the database
• Cacheable - Results can be cached and reused
• Reactive - Client automatically subscribes to updates
• Transactional - Reads are strongly consistent

export const getMessage = query({
  args: { id: v.id("messages") },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.id);
  },
});

​

Mutations

• Read-write - Can read and modify the database
• Transactional - ACID guarantees for all operations
• Consistent - All reads within a mutation see a consistent snapshot
• Triggers reactivity - Changes trigger query updates

export const sendMessage = mutation({
  args: { body: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.insert("messages", { body: args.body });
  },
});

​

Actions

• Side effects - Can call external APIs and services
• Long-running - Configurable timeout for extended operations
• Non-deterministic - Can use randomness, current time, etc.
• Can call queries and mutations - Orchestrate multiple database operations

"use node";
import { action } from "./_generated/server";

export const sendEmail = action({
  args: { email: v.string() },
  handler: async (ctx, args) => {
    // Call external API
    await fetch("https://api.email-service.com/send", {
      method: "POST",
      body: JSON.stringify({ to: args.email }),
    });
    
    // Record in database
    await ctx.runMutation(api.emails.recordSent, { email: args.email });
  },
});

​

Storage architecture

​

SQLite (default)

• Best for: Development, small deployments, single-server setups
• Location: Local file in Docker volume or filesystem
• Performance: Excellent for single-server workloads
• Scaling: Vertical scaling only

​

Postgres

• Best for: Production deployments requiring high availability
• Providers: Neon, RDS, self-hosted
• Performance: Excellent with proper co-location
• Scaling: Managed service handles replication and backups

​

MySQL/Vitess

• Best for: Teams already using MySQL infrastructure
• Providers: PlanetScale, RDS MySQL, self-hosted
• Performance: Comparable to Postgres
• Scaling: Vitess provides horizontal scaling capabilities

​

S3 storage (optional)

• Exports - Backup data exports
• Snapshots - Point-in-time snapshots
• Modules - Bundled function code
• Files - User-uploaded files
• Search indexes - Full-text and vector search indexes

​

Deployment considerations

​

Resource requirements

• Minimum: 512MB RAM, 1 CPU core
• Recommended: 2GB+ RAM, 2+ CPU cores
• Storage: Depends on your data size plus indexes

​

Scaling strategies

​

High availability

1. Use managed Postgres or MySQL with automatic failover
2. Deploy backend containers across multiple availability zones
3. Configure load balancer health checks using /version endpoint
4. Set up monitoring and alerting for backend and database
5. Regular backups using npx convex export

​

Security considerations

​

Authentication

• Convex Auth - Built-in authentication system (requires manual setup for self-hosted)
• Third-party providers - Clerk, WorkOS, Auth0, etc.
• Custom JWT - Bring your own auth provider

​

Network security

• Use HTTPS/TLS for all production deployments
• Set DO_NOT_REQUIRE_SSL=1 only for local development
• Restrict dashboard access to trusted networks
• Rotate admin keys periodically
• Never commit .env.local to version control

​

Telemetry beacon

​

Next steps