convex-domain-folder

Convex domain-folder structure

The mental model

A Convex backend tends to start flat: convex/tasks.ts, convex/users.ts, one giant convex/schema.ts. As it grows, the clean end state is one folder per domain, where each domain owns its tables and its functions:

convex/
  schema.ts              # just spreads: ...usersTables, ...tasksTables, ...
  http.ts                # thin composition root: calls each registerXRoutes(app)
  tasks/
    schema.ts            # exports tasksTables (table defs, NOT defineSchema)
    queries.ts           # api.tasks.queries.*  (single-tier domain, no trust split needed)
    mutations.ts         # api.tasks.mutations.*
    model.ts             # shared helpers/validators (no Convex functions)
    tasks.test.ts        # co-located test (needs glob re-rooting, see below)
  companies/
    schema.ts            # data-only domain -> schema.ts is the ONLY file
  users/
    schema.ts            # exports usersTables
    helpers.ts            # shared helpers, used across ALL tiers below (not tiered itself)
    validators.ts          # shared validators, ditto
    triggers.ts            # Convex triggers, ditto
    internal/
      queries.ts          # api path: internal.users.internal.queries.*  (internalQuery)
      mutations.ts        # internalMutation — convex-only, never client-callable
    private/
      queries.ts          # api.users.private.queries.*  (query, requires an authed user)
      mutations.ts        # api.users.private.mutations.*
      actions.ts           # action, also requires an authed user
    public/
      queries.ts           # api.users.public.queries.*  (query, no auth required)

The root schema.ts becomes a thin composition root — a few imports and spreads, zero inline table definitions. Adding a new domain then costs one import + one spread, with no central file to keep editing.

The single most important fact: moving a file into a subfolder changes its Convex function paths, because Convex derives module names from the file path. convex/tasks.ts → api.tasks.*; convex/tasks/queries.ts → api.tasks.queries.*. Every call site must be repointed. This is not a pure rename — plan for the blast radius before you start.