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.

VeloIQConfig is a Python dataclass accepted by create_veloiq_app(). Every field reads from an environment variable when not set explicitly, so you can configure the application entirely through a .env file following 12-factor app conventions. Override individual fields in code when you need app-specific values that should not come from the environment.

​
Quick example

from veloiq_framework import create_veloiq_app, VeloIQConfig

app = create_veloiq_app(VeloIQConfig(
    title="Acme Admin",
    database_url="postgresql://user:pass@localhost/acme",
    cors_origins=["http://localhost:5173"],
    admin_title="Acme Back-Office",
))

​
Database

FieldEnv varDefaultDescription
database_urlDATABASE_URL—SQLAlchemy database URL. Required. Supports SQLite (sqlite:///./app.db) and PostgreSQL (postgresql://user:pass@host/db).
echo_sqlVELOIQ_ECHO_SQLFalseLog all SQL statements to stdout. Useful for debugging; disable in production.
create_tables_on_startup—TrueCall SQLModel.metadata.create_all() on startup. Set to False when managing schema with Alembic migrations.

​
Application

FieldEnv varDefaultDescription
title—"VeloIQ App"FastAPI application title shown in /docs and the admin panel.
modules_dirVELOIQ_MODULES_DIR"app/modules"Path to the modules directory, relative to the working directory. The framework discovers models.py, api.py, custom_api.py, and admin/admin_views.py inside each sub-folder.
static_dir—NoneDirectory to mount at /static. When None, no static mount is added.

​
CORS

FieldEnv varDefaultDescription
cors_originsCORS_ORIGINS["http://localhost:5173", "http://127.0.0.1:5173", "http://localhost:3000", "http://127.0.0.1:3000"]Allowed CORS origins. In the environment variable, supply a comma-separated list. The default permits the standard Vite and Create React App dev ports.
The default cors_origins value in the code differs from the documentation shorthand ["*"] — it permits the standard local dev ports. In production, always set CORS_ORIGINS explicitly to your frontend domain(s).

​
Auth

FieldEnv varDefaultDescription
auth_enabledVELOIQ_AUTH_DISABLEDTrueEnable JWT Bearer token middleware. Set VELOIQ_AUTH_DISABLED=1 to disable auth enforcement (development only).
auth_secretAUTH_SECRET"veloiq-dev-secret-change-me"Secret key used to sign and verify JWT tokens.
auth_algorithm—"HS256"JWT signing algorithm.
auth_token_expire_minutesAUTH_TOKEN_EXPIRE_MINUTES480Token validity in minutes (default 8 hours).
Never use the default auth_secret in production. Set AUTH_SECRET to a long, random string before deploying. Any deployment with the default secret is trivially forgeable.

​
Initial admin seed credentials

These fields control the default admin user created on first startup. Once the user exists in the database, changing them has no effect.
FieldEnv varDefaultDescription
admin_usernameVELOIQ_ADMIN_USERNAME"admin"Username for the seeded admin account.
admin_passwordVELOIQ_ADMIN_PASSWORD"admin"Password for the seeded admin account. Change before first deployment.

​
Admin panel

FieldEnv varDefaultDescription
admin_title—Same as titleTitle shown in the SQLAdmin back-office at /admin/.
admin_logo_url—NoneURL of the logo image displayed in the admin panel header.
admin_templates_dir—NonePath to a custom Jinja2 templates directory for SQLAdmin overrides.

​
Roles

FieldEnv varDefaultDescription
roles—DEFAULT_ROLESList of RoleDef objects upserted to the database on startup. Defaults to the built-in Admin, Manager, and Viewer presets. Replace or extend this list to introduce application-specific roles.
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 access",            is_preset=True),
        RoleDef("Manager", WRITE_METHODS, "Create/edit, no delete", is_preset=True),
        RoleDef("Viewer",  READ_METHODS,  "Read-only",              is_preset=True),
        RoleDef("Auditor", READ_METHODS,  "External auditor",       is_preset=True),
    ],
))

​
ReBAC

FieldEnv varDefaultDescription
rebac_enabledVELOIQ_REBAC_ENABLEDFalseEnable row-level access control globally. Individual models still require the @rebac decorator.

​
Environment variable reference

# Required
DATABASE_URL=postgresql://user:password@localhost/dbname

# Application
VELOIQ_MODULES_DIR=app/modules

# CORS (comma-separated)
CORS_ORIGINS=http://localhost:5173,https://yourdomain.com

# Auth
VELOIQ_AUTH_DISABLED=0
AUTH_SECRET=your-secret-key-here
AUTH_TOKEN_EXPIRE_MINUTES=480

# ReBAC
VELOIQ_REBAC_ENABLED=0

# Database debugging
VELOIQ_ECHO_SQL=false

# Initial admin seed (first startup only)
VELOIQ_ADMIN_USERNAME=admin
VELOIQ_ADMIN_PASSWORD=admin

Python API

Full reference for all public symbols exported from veloiq_framework.

CRUD Router

Auto-generated endpoint reference and query parameter details.