> ## Documentation Index
> Fetch the complete documentation index at: https://confect.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Structure

> Understand the structure of a Confect project.

<Tree>
  <Tree.Folder name="confect" defaultOpen>
    <Tree.Folder name="_generated" defaultOpen>
      <Tree.File name="components.ts" />

      <Tree.File name="convexSchema.ts" />

      <Tree.File name="docs.ts" />

      <Tree.File name="id.ts" />

      <Tree.File name="refs.ts" />

      <Tree.File name="schema.ts" />

      <Tree.File name="services.ts" />

      <Tree.File name="spec.ts" />

      <Tree.Folder name="registeredFunctions" defaultOpen>
        <Tree.File name="env.ts" />

        <Tree.Folder name="notes_and_random" defaultOpen>
          <Tree.File name="notes.ts" />

          <Tree.File name="random.ts" />
        </Tree.Folder>

        <Tree.File name="workpool.ts" />
      </Tree.Folder>

      <Tree.Folder name="tables" defaultOpen>
        <Tree.File name="notes.ts" />

        <Tree.File name="users.ts" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="notes_and_random" defaultOpen>
      <Tree.File name="notes.spec.ts" />

      <Tree.File name="notes.impl.ts" />

      <Tree.File name="random.spec.ts" />

      <Tree.File name="random.impl.ts" />
    </Tree.Folder>

    <Tree.Folder name="middleware" defaultOpen>
      <Tree.File name="RequireUser.spec.ts" />

      <Tree.File name="RequireUser.impl.ts" />
    </Tree.Folder>

    <Tree.Folder name="tables" defaultOpen>
      <Tree.File name="notes.ts" />

      <Tree.File name="users.ts" />
    </Tree.Folder>

    <Tree.File name="auth.ts" />

    <Tree.File name="crons.ts" />

    <Tree.File name="env.spec.ts" />

    <Tree.File name="env.impl.ts" />

    <Tree.File name="http.ts" />

    <Tree.File name="workpool.spec.ts" />

    <Tree.File name="workpool.impl.ts" />
  </Tree.Folder>

  <Tree.Folder name="convex" />
</Tree>

## `confect/`

### `_generated/`

#### `components.ts`

Contains a typed `components` registry with one entry per Convex [component](https://docs.convex.dev/components) installed via `app.use(...)` in `convex/convex.config.ts`. Use it wherever a component client expects a component reference (e.g. `new Workpool(components.workpool, ...)`). Unlike the `components` export of `convex/_generated/api`, this file is safe to import from your impl files' import graphs. See [Components](/v10/server/components).

#### `convexSchema.ts`

Contains the Convex deploy-time `SchemaDefinition` (a single `defineSchema({...})` call) assembled from every `confect/tables/*.ts` module. `convex/schema.ts` re-exports its default so Convex's CLI and `convex-test` find it where they expect. You should never import this file directly from your own code—use `_generated/schema.ts` for runtime needs.

#### `docs.ts`

Contains a named TypeScript `interface` for each table's document—`NotesDoc`, `UsersDoc`, etc.—plus a `Docs` registry mapping each table name to its interface. These are pure types (no runtime code): use them to annotate a value with a table's document type, e.g. `const note: NotesDoc = …`. The `Docs` registry is what lets the `DatabaseReader`/`DatabaseWriter` services hand documents back under their named types. See [Document types](/v10/server/database/schema#document-types).

#### `id.ts`

Contains a type-constrained `Id` constructor whose only argument is the union of your table names—for example, `Id("users")` returns the `Schema` for an `_id` value in the `users` table. Use this when defining cross-table references (e.g. a `userId: Id("users")` field) and inside spec `args` fields or `returns` schemas. The type-level constraint catches typos at compile time, replacing the loosely-typed `GenericId.GenericId("users")` form.

#### `registeredFunctions/`

Contains one module per group (for example `registeredFunctions/notes_and_random/notes.ts`), each exporting that group's functions in a form the Convex CLI can consume. These modules are consumed by the generated `convex/` files; you should not need to import them directly.

#### `refs.ts`

Contains a single default `Refs` export, which is a map of your Convex functions and their [function names](https://docs.convex.dev/api/modules/server#getfunctionname) and args/returns `Schema`s. Use this to invoke your Convex functions from the client or inside Convex functions using the `*Runner` services (`QueryRunner`, `MutationRunner`, and `ActionRunner`).

#### `schema.ts`

Contains the runtime `DatabaseSchema`—the codec-lookup view of your tables. Impls import it and pass it to `FunctionImpl.make`/`GroupImpl.make`. It is generated from `confect/tables/*.ts` and intentionally avoids any `convex/server` import so a runtime cold start never evaluates `defineSchema(...)`. Each table's field-schema is constructed lazily on the first access to its `Fields` or `Doc` and then cached, so a function only pays the schema-construction cost at cold start for the tables it actually touches via `db.table(name)`. Use this when a test or a non-codegen-generated module needs to refer to your `DatabaseSchema` type or value.

#### `tables/`

Contains one wrapper module per user-authored table (for example `tables/notes.ts` for `confect/tables/notes.ts`). Each wrapper applies the filename-derived table name to the `Table` defined in `confect/tables/<name>.ts` and re-exports it as the default. Specs, impls, and other consumers should default-import from `confect/_generated/tables/<name>` to reach a table's `Doc`, `Fields`, and `tableName` properties—for example, `import notes from "../_generated/tables/notes"` and then `notes.Doc`. These wrappers are client-safe: they do not import `@confect/server`, so a spec that uses `notes.Doc` can ship in `_generated/refs.ts` without pulling the server package into the browser.

#### `services.ts`

Contains Effect service wrappers for Convex platform capabilities, scoped to your app's database schema. Use these in your function implementation handlers. See [Services](/v10/concepts/services) for a full list.

#### `spec.ts`

Contains your assembled Confect spec—every function group, of any runtime (including Node action groups)—used to build `refs.ts`.

### `auth.ts`

<Badge color="yellow">Optional</Badge>

Corresponds 1:1 with `convex/auth.config.ts`. Use this to [configure auth](https://docs.convex.dev/auth).

### `crons.ts`

<Badge color="yellow">Optional</Badge>

Expects a default `CronJobs` export defining your [cron jobs](/v10/server/cron-jobs).

### `http.ts`

<Badge color="yellow">Optional</Badge>

Expects a default Convex `HttpRouter` export. Construct this using Confect's `HttpRouter.make` and Effect's `effect/unstable/http`/`effect/unstable/httpapi` modules.

### `tables/`

<Badge color="green">Required</Badge>

Defines your database tables, one file per table. The **filename is the table name**—`confect/tables/notes.ts` defines a table called `notes`—so filenames must be valid JS identifiers and may not start with `_` (Convex reserves underscore-prefixed names for system tables). Each module **must default-export a `Table`** (built with `Table.make(...)` from `@confect/core`); codegen reads `module.default`, validates the filename, and applies it as the table name to produce `_generated/tables/<name>.ts`. Other modules import from the wrapper, not directly from `tables/`. Codegen also scans this directory to produce `_generated/schema.ts` (runtime), `_generated/convexSchema.ts` (deploy), and `_generated/id.ts` (the cross-table `Id` constructor). See [Schema](/v10/server/database/schema).

### `middleware/`

<Badge color="yellow">Optional</Badge>

Defines your [middleware](/v10/server/middleware), as a `<Name>.spec.ts`/`<Name>.impl.ts` pair per middleware. Like `tables/`, this directory name is reserved: Confect does not scan it for function groups, so its spec/impl pairs declare and implement middleware rather than a group, and no `convex/` module is emitted for them. Middleware is shared across groups, which is why it lives here rather than inside any one group's spec.

### `*.spec.ts`/`*.impl.ts`

<Badge color="green">Required</Badge>

Your Convex API is defined as colocated `*.spec.ts`/`*.impl.ts` pairs, one pair per group. Each file's path within `confect/` becomes the group's name. See [File Naming Conventions](/v10/concepts/file-naming-conventions) and [The Spec/Impl Model](/v10/concepts/spec-impl-model).

## Rules

* Your `confect/` directory should always be a sibling of your `convex/` directory.
* The `confect/_generated/` directory is generated by the Confect CLI. You should never modify files in this directory directly.
* Spec modules are bundled into your client, so nothing a `*.spec.ts` reaches may value-import `@confect/server` (`tables/` and `_generated/` excepted, since a `Table` needs it); use `import type` when you only need the types. `confect codegen` enforces this.
* Confect treats the `convex` directory as a codegen target. While using Confect, you should never modify files in the `convex` folder directly, except for `tsconfig.json` and `convex.config.ts`.