convex-structure

Convex Structure

Downstream contract: paths like src/ and convex/ refer to the product workspace that adopts Agentic Ship, not this tool repo.

Official Convex skills (from the convex plugin) teach Convex. This skill teaches Convex inside this repo — the conventions that let an agent open a cold codebase and know exactly where everything goes without reading it all first.

Every rule here is deterministic. If you find yourself deciding, you have missed a rule.

1. File layout — one domain per file

convex/
  schema.ts              every table, every index. Nothing exists unless declared here.
  convex.config.ts       component registration (Better Auth, and later others)
  auth.config.ts         auth provider declaration
  auth.ts                createAuth + authComponent. Plugins toggle here.
  http.ts                httpRouter: auth routes + inbound webhooks. Nothing else.
  <domain>.ts            (you create) the entire public API of one domain, e.g. posts.ts
  lib/
    auth.ts              requireUser / requireOwner helpers
    validators.ts        (you create) shared validator fragments, once two domains share one
  _generated/            created by `npx convex dev`; committed then, never edited by hand

Rules:

• A domain gets its own file the moment it owns a table. users.ts, posts.ts, waitlist.ts. Never a utils.ts dumping ground, never a functions.ts.
• Domain names are plural nouns matching the table name. Table posts → file convex/posts.ts → frontend feature folder src/components/features/posts/. One word, three places, no translation needed.
• Cross-domain reads go through the owning domain's file. If posts.ts needs a user, it calls a helper from lib/auth.ts — it does not query the users table directly. One writer per table.

2. Function shape — the only accepted template

Every function, without exception:

export const create = mutation({
  args: { title: v.string() },              // ALWAYS present
  returns: v.id("posts"),                   // ALWAYS present
  handler: async (ctx, args) => {
    const user = await requireUser(ctx);    // identity from ctx, never from args
    return await ctx.db.insert("posts", { title: args.title, userId: user._id });
  },
});