Convex Backend

The backend lives in packages/backend/src/convex/ and uses Convex for real-time database, serverless functions, and scheduled jobs.

Schema

The database schema is defined in packages/backend/src/convex/schema.ts. Each module contributes its own table definitions which are merged into the root schema.

Function types

Convex provides three function types:

• Queries — Read-only, automatically reactive. Clients re-render when underlying data changes.
• Mutations — Read-write, transactional. Run in a single transaction with automatic retries on conflicts.
• Actions — Can call external APIs, run non-deterministic code. Not transactional.

Module structure

Each module under modules/ follows a consistent pattern:

modules/core/billing/
├── billing_api.ts        # Public queries & mutations
├── billing_internal.ts   # Internal functions
└── billing_table.ts      # Table definition & validators

Frontend integration

The frontend imports from the backend package:

import { api } from "@red/backend/api"
import { useQuery, useMutation } from "convex/react"

// Reactive query — auto-updates when data changes
const user = useQuery(api.modules.core.auth.auth_api.currentUser)

// Mutation
const updateName = useMutation(api.modules.core.auth.auth_api.updateName)