veloiq new: Scaffold a Full-Stack VeloIQ Project

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

Option	Default	Description
`--title <text>`	Derived from `<app-name>`	Human-readable app title substituted throughout generated files
`--port <number>`	`8000`	Backend 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.

File	Tool
`CLAUDE.md`	Claude Code
`.cursor/rules/veloiq.mdc`, `.cursor/rules/models.mdc`	Cursor
`.windsurfrules`	Windsurf
`AGENTS.md`	Codex / OpenAI Agents
`.github/copilot-instructions.md`	GitHub Copilot
`.continue/config.json`	Continue

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

Flag	Effect
`--with-custom-api`	Also creates `custom_api.py` — a stub for custom FastAPI endpoints that import from the generated `api.py` router
`--with-admin`	Also 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.

CLI

Python API

React UI Library

veloiq new: Scaffold a Full-Stack VeloIQ Project

Usage

Options

Examples

Generated project structure

Key generated files

AI context files

Adding modules to an existing project

Optional flags

​Usage

​Options

​Examples

​Generated project structure

​Key generated files

​AI context files

​Adding modules to an existing project

​Optional flags

Usage

Options

Examples

Generated project structure

Key generated files

AI context files

Adding modules to an existing project

Optional flags