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

# veloiq generate: Generate API and Frontend Schemas

> The veloiq generate command reads your SQLModel definitions and writes api.py CRUD endpoints and TypeScript schemas for the React frontend.

`veloiq generate` is the bridge between your Python model definitions and the rest of the stack. It scans every module under `backend/app/modules/`, reads the SQLModel class definitions in each `models.py`, and writes two output files per module: a fully-wired FastAPI CRUD router (`api.py`) and a TypeScript field schema (`{module}Schema.gen.ts`). It also rewrites the top-level `allModels.gen.ts` registry that the React frontend uses to render dynamic CRUD pages. Run it every time you add a field, add a model, or change an access control annotation.

## Usage

Run from your project root or from the `backend/` directory:

```bash theme={null}
veloiq generate
```

### Options

| Option                  | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| `--modules-dir <path>`  | Path to the modules directory (default: auto-detected) |
| `--frontend-src <path>` | Path to `frontend/src` (default: auto-detected)        |
| `--project-root <path>` | Explicit project root (default: CWD)                   |

The defaults work for any project created with `veloiq new`. Pass explicit paths only when your project layout differs from the standard scaffold.

## What gets generated

For each module `veloiq generate` writes or overwrites the following files.

### `backend/app/modules/{module}/api.py`

A complete FastAPI router with standard CRUD endpoints: list, show, create, update, and delete. The router enforces the RBAC rules derived from `@model_access` annotations on your model class.

```
backend/app/modules/products/api.py   ← DO NOT EDIT
```

Add custom endpoints in `custom_api.py` instead — it imports `router` from `api.py` and adds endpoints to the same prefix.

### `frontend/src/pages/{module}/{module}Schema.gen.ts`

TypeScript field definitions consumed by the `@veloiq/ui` dynamic CRUD components (`DynamicList`, `DynamicShow`, `DynamicCreate`, `DynamicEdit`). The schema describes each field's type, label, and access rules as derived from your `veloiq_field` annotations.

```
frontend/src/pages/products/productsSchema.gen.ts   ← DO NOT EDIT
```

### `frontend/src/allModels.gen.ts`

A top-level registry that collects every module schema and exports a unified model list. The React app imports this file on startup to build the navigation and route structure.

```
frontend/src/allModels.gen.ts   ← DO NOT EDIT
```

<Warning>
  Never edit any generated file. Every `api.py`, `*Schema.gen.ts`, and `allModels.gen.ts` is completely overwritten the next time you run `veloiq generate`. Put custom logic in `custom_api.py` or your own non-generated source files.
</Warning>

## When to re-run

Re-run `veloiq generate` after any of the following changes to a model:

* Adding or removing a field
* Changing a field's type or default value
* Adding, removing, or modifying a `veloiq_field(...)` annotation (read/write roles, display options)
* Adding or modifying a `@model_access(...)` decorator
* Adding a new model class to a `models.py`
* Adding a new module directory

## Typical workflow

```bash theme={null}
# 1. Edit or add fields in your model
# backend/app/modules/products/models.py

# 2. Regenerate API and schemas
veloiq generate

# 3. If the schema changed (new table or column), create and apply the migration
veloiq db migrate -m "add sku field to product"
veloiq db upgrade
```

<Tip>
  After running `veloiq generate`, check whether your model changes require a database migration. If you added or removed columns, always follow up with `veloiq db migrate` and `veloiq db upgrade` before starting the server.
</Tip>