> ## 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="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](/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](/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`/`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`, `Doc`, or `tableDefinition` 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`.

#### `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](/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](/server/cron-jobs).

### `http.ts`

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

Expects a default Convex `HttpRouter` export. Construct this using Confect's `HttpApi.make` and `@effect/platform`'s [HTTP API modules](https://github.com/Effect-TS/effect/blob/main/packages/platform/README.md#http-api).

### `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(...)`); 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](/server/database/schema).

### `*.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](/concepts/file-naming-conventions) and [The Spec/Impl Model](/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.
* 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`.