> ## 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: Scaffold a Full-Stack VeloIQ Project

> The veloiq new command scaffolds a complete full-stack project with backend, frontend, environment config, and code generation entry point.

`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

```bash theme={null}
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

```bash theme={null}
veloiq new my-app
veloiq new acme-admin --title "Acme Admin" --port 8080
veloiq new my-app --output-dir /projects/my-app
```

<Note>
  `<app-name>` is slugified automatically — spaces and special characters are converted to hyphens. `My App` becomes `my-app`.
</Note>

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

```python theme={null}
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.

```bash theme={null}
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`.

<Warning>
  Never edit `api.py` or any `*.gen.ts` file. They are overwritten by `veloiq generate`.
</Warning>

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

```bash theme={null}
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)                                             |

```bash theme={null}
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`.