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

# Get started with VeloIQ in under 15 minutes

> Install the VeloIQ CLI, scaffold a project, define your first model, generate the API and frontend, and launch your app in minutes.

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.

<Steps>
  <Step title="Install the CLI">
    Install the `veloiq-framework` package from PyPI. This installs both the Python framework and the `veloiq` CLI.

    ```bash theme={null}
    pip install veloiq-framework
    ```

    Verify the installation:

    ```bash theme={null}
    veloiq --version
    ```
  </Step>

  <Step title="Create a project">
    Scaffold a new project with `veloiq new`. The command creates a fully-wired backend and frontend in a single directory.

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

  <Step title="Configure the database">
    Copy `.env.example` to `.env` and set your `DATABASE_URL`.

    ```bash theme={null}
    cd backend
    cp .env.example .env
    ```

    Open `.env` and set the database connection. VeloIQ supports any SQLAlchemy-compatible database.

    <Tabs>
      <Tab title="SQLite (default)">
        SQLite requires no server and is the easiest way to get started locally.

        ```bash theme={null}
        DATABASE_URL=sqlite:///./app.db
        ```
      </Tab>

      <Tab title="PostgreSQL">
        For production or when you need a full relational database:

        ```bash theme={null}
        DATABASE_URL=postgresql://user:pass@localhost/myapp
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add your first module">
    Run `veloiq add-module` to scaffold the module directory, then open the generated `models.py` and define your model.

    ```bash theme={null}
    veloiq add-module products
    ```

    Edit `backend/app/modules/products/models.py`:

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

  <Step title="Generate the API and TypeScript schemas">
    Run `veloiq generate` from the `backend` directory. The command reads your model definitions and writes two files.

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

  <Step title="Start the backend">
    Install the Python dependencies, apply the database migrations to create your tables, then start the development server.

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

  <Step title="Start the frontend">
    Open a new terminal, move into the frontend directory, install dependencies, and start the Vite dev server.

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

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

<Tip>
  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](/tutorial).
</Tip>