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 new creates a ready-to-run VeloIQ project in a single command. It copies the framework’s scaffold templates, applies your app name throughout all generated files, and sets up both the Python backend and the React frontend — including Alembic migration support and AI context files for common coding tools.

​
Usage

veloiq new <app-name>

​
Options

OptionDefaultDescription
--title <text>Derived from <app-name>Human-readable app title substituted throughout generated files
--port <number>8000Backend port the frontend proxy will target
--output-dir <path>./<app-name>Directory to create the project in

​
Examples

veloiq new my-app
veloiq new acme-admin --title "Acme Admin" --port 8080
veloiq new my-app --output-dir /projects/my-app
<app-name> is slugified automatically — spaces and special characters are converted to hyphens. My App becomes my-app.

​
Generated project structure

my-app/
├── backend/
│   ├── app/
│   │   ├── main.py               # Entry point — do not edit
│   │   └── modules/              # Your feature modules go here
│   ├── alembic/                  # Alembic migrations directory
│   ├── alembic.ini               # Alembic configuration
│   ├── .env.example              # All supported environment variables
│   ├── requirements.txt
│   └── api_schema_gen.py         # Code generation entry point
├── frontend/
│   ├── src/
│   │   ├── App.tsx               # Clean ~50-line app shell
│   │   ├── main.tsx
│   │   └── allModels.gen.ts      # Auto-generated — do not edit
│   ├── public/
│   │   └── i18n/
│   │       ├── en.json
│   │       └── es.json
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts
├── CLAUDE.md
├── AGENTS.md
├── .windsurfrules
└── .cursor/
    └── rules/
        ├── veloiq.mdc
        └── models.mdc

​
Key generated files

backend/app/main.py — The complete application is created by a single call to create_veloiq_app. The module auto-loader, admin UI, auth system, and CORS are all wired up automatically. 
from veloiq_framework import create_veloiq_app, VeloIQConfig, RoleDef, ALL_METHODS, WRITE_METHODS, READ_METHODS

app = create_veloiq_app(VeloIQConfig(
    roles=[
        RoleDef("Admin",   ALL_METHODS,   "Full administrative access",        is_preset=True),
        RoleDef("Manager", WRITE_METHODS, "Create, edit and view — no delete", is_preset=True),
        RoleDef("Viewer",  READ_METHODS,  "Read-only access",                  is_preset=True),
    ],
))
backend/.env.example — All supported environment variables with inline documentation. Copy this to .env before running the backend. 
DATABASE_URL=sqlite:///./app.db
AUTH_SECRET=change-me-to-a-random-64-char-string
# AUTH_TOKEN_EXPIRE_MINUTES=480
# VELOIQ_AUTH_DISABLED=1
# VELOIQ_ADMIN_USERNAME=admin
# VELOIQ_ADMIN_PASSWORD=admin
# VELOIQ_ECHO_SQL=1
backend/api_schema_gen.py — The entry point for code generation. Running veloiq generate calls this file internally; you can also invoke it directly with python api_schema_gen.py. frontend/src/App.tsx — A clean application shell (~50 lines) that wires together routing, auth, and the Refine data provider. You rarely need to edit this file. frontend/src/allModels.gen.ts — A registry of all module schemas consumed by the frontend’s dynamic CRUD pages. This file is overwritten every time you run veloiq generate.
Never edit api.py or any *.gen.ts file. They are overwritten by veloiq generate.

​
AI context files

veloiq new writes context files that teach AI coding assistants the VeloIQ conventions for your project. Each tool reads its own file automatically.
FileTool
CLAUDE.mdClaude Code
.cursor/rules/veloiq.mdc, .cursor/rules/models.mdcCursor
.windsurfrulesWindsurf
AGENTS.mdCodex / OpenAI Agents
.github/copilot-instructions.mdGitHub Copilot
.continue/config.jsonContinue
All files encode the same workflow: use veloiq add-module, edit models.py, run veloiq generate, run veloiq db upgrade, and never manually edit generated files.

​
Adding modules to an existing project

After the initial scaffold, use veloiq add-module to add feature modules one at a time: 
veloiq add-module inventory
This creates the module skeleton under backend/app/modules/inventory/: 
backend/app/modules/inventory/
├── __init__.py
└── models.py          # starter model — edit this to define your fields

​
Optional flags

FlagEffect
--with-custom-apiAlso creates custom_api.py — a stub for custom FastAPI endpoints that import from the generated api.py router
--with-adminAlso creates admin/__init__.py and admin/admin_views.py — a SQLAdmin view stub
--project-root <path>Explicit project root (default: auto-detected by walking up from CWD)
veloiq add-module inventory --with-custom-api --with-admin
After creating a module, edit models.py to define your fields, then run veloiq generate followed by veloiq db upgrade.