Skip to main content

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 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: 
veloiq generate

​
Options

OptionDescription
--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
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.

​
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

# 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
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.