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.

This guide takes you from a blank machine to a running full-stack application with a REST API, a React frontend, and an admin back-office. You will install the CLI, scaffold a project, add a model, and launch both servers.
1

Install the CLI

Install the veloiq-framework package from PyPI. This installs both the Python framework and the veloiq CLI.
pip install veloiq-framework
Verify the installation:
veloiq --version
2

Create a project

Scaffold a new project with veloiq new. The command creates a fully-wired backend and frontend in a single directory.
veloiq new my-app
cd my-app
The scaffolded structure looks like this:
my-app/
├── backend/
│   ├── app/
│   │   ├── main.py          # app = create_veloiq_app()
│   │   └── modules/         # your domain modules go here
│   ├── .env.example
│   ├── requirements.txt
│   └── api_schema_gen.py    # code generator entry point
└── frontend/
    ├── src/
    │   ├── App.tsx           # ~50-line app shell
    │   └── allModels.gen.ts  # auto-generated, do not edit
    ├── package.json
    └── vite.config.ts
3

Configure the database

Copy .env.example to .env and set your DATABASE_URL.
cd backend
cp .env.example .env
Open .env and set the database connection. VeloIQ supports any SQLAlchemy-compatible database.
SQLite requires no server and is the easiest way to get started locally.
DATABASE_URL=sqlite:///./app.db
4

Add your first module

Run veloiq add-module to scaffold the module directory, then open the generated models.py and define your model.
veloiq add-module products
Edit backend/app/modules/products/models.py:
from typing import Optional
from veloiq_framework import TimestampedModel

class Product(TimestampedModel, table=True):
    __tablename__ = "product"

    name: str
    price: float
    in_stock: bool = True
    description: Optional[str] = None
TimestampedModel automatically adds id, created_at, and updated_at columns. If you don’t want timestamp columns, use FrameworkModel instead — it provides only the id primary key.
5

Generate the API and TypeScript schemas

Run veloiq generate from the backend directory. The command reads your model definitions and writes two files.
veloiq generate
It creates:
  • backend/app/modules/products/api.py — standard CRUD REST endpoints for the Product model
  • frontend/src/pages/products/productsSchema.gen.ts — TypeScript field definitions for the React frontend
Do not edit these files by hand. Re-run veloiq generate whenever you change a model.
6

Start the backend

Install the Python dependencies, apply the database migrations to create your tables, then start the development server.
pip install -r requirements.txt
veloiq db upgrade
veloiq run
The backend starts at http://localhost:8000. Two interfaces are available immediately:
  • API docs — http://localhost:8000/docs — interactive Swagger UI for every endpoint
  • Admin panel — http://localhost:8000/admin/ — SQLAdmin back-office with search, sort, and filter
7

Start the frontend

Open a new terminal, move into the frontend directory, install dependencies, and start the Vite dev server.
cd ../frontend
npm install
npm run dev
Open http://localhost:5173. You have a working React CRUD interface for the Product model — list, show, create, edit, and delete — with sorting, filtering, and bulk actions, and no additional code.
8

Log in

The login screen appears at http://localhost:5173. Use the default admin credentials seeded on first startup:
  • Username: admin
  • Password: admin
After logging in, you will see the sidebar with your Products module listed. Click it to open the list view and start creating records.
Before deploying to production, set a strong AUTH_SECRET value in your .env file and change the admin password. The default credentials are seeded only on first startup — update them in the admin panel or via the API before your app is publicly accessible.
This quickstart covers the essentials. To learn about model relations, custom endpoints, RBAC, row-level access control, and the full UI feature set, work through the Tutorial.