VeloIQ Tutorial: Build a Full Task Manager App

cd ~/projects          # or wherever you keep your code
git clone https://github.com/cesarlugos1s/VeloIQ.git
cd VeloIQ
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e backend/
veloiq new task-manager
cd task-manager

task-manager/
├── backend/
│   ├── app/
│   │   ├── main.py          # one line
│   │   └── modules/         # your modules go here
│   ├── .env.example
│   ├── requirements.txt
│   └── api_schema_gen.py
└── frontend/
    ├── src/
    │   ├── App.tsx
    │   └── allModels.gen.ts
    └── package.json

from veloiq_framework import create_veloiq_app
app = create_veloiq_app()

cd backend
cp .env.example .env

cd ..                  # back to task-manager/
veloiq add-module team
veloiq add-module projects
veloiq add-module tasks

backend/app/modules/
├── team/
│   ├── __init__.py
│   └── models.py          ← fill this in
├── projects/
│   ├── __init__.py
│   └── models.py          ← fill this in
└── tasks/
    ├── __init__.py
    └── models.py          ← fill this in

from typing import List
from veloiq_framework import TimestampedModel, jm_relationship


class TeamMember(TimestampedModel, table=True):
    __tablename__ = "team_member"

    name: str
    email: str
    role: str = "member"

    owned_projects: List["Project"] = jm_relationship(back_populates="owner")
    assigned_tasks: List["Task"] = jm_relationship(back_populates="assignee")

from typing import List, Optional
from sqlmodel import Field
from veloiq_framework import TimestampedModel, jm_relationship


class Project(TimestampedModel, table=True):
    __tablename__ = "project"

    name: str
    description: Optional[str] = None
    status: str = "active"

    owner_id: Optional[int] = Field(default=None, foreign_key="team_member.id")
    owner: Optional["TeamMember"] = jm_relationship(back_populates="owned_projects")
    tasks: List["Task"] = jm_relationship(back_populates="project")

import datetime
from typing import List, Optional
from sqlmodel import Field
from veloiq_framework import TimestampedModel, jm_relationship


class Task(TimestampedModel, table=True):
    __tablename__ = "task"

    title: str
    description: Optional[str] = None
    status: str = "todo"        # todo | in_progress | done
    priority: str = "medium"    # low | medium | high | critical
    due_date: Optional[datetime.date] = None
    planned_work_hours: Optional[float] = None
    actual_work_hours: Optional[float] = None

    project_id: Optional[int] = Field(default=None, foreign_key="project.id")
    project: Optional["Project"] = jm_relationship(back_populates="tasks")

    assignee_id: Optional[int] = Field(default=None, foreign_key="team_member.id")
    assignee: Optional["TeamMember"] = jm_relationship(back_populates="assigned_tasks")

    # Self-referential: a task can have sub-tasks
    parent_task_id: Optional[int] = Field(default=None, foreign_key="task.id")
    subtasks: List["Task"] = jm_relationship(
        back_populates="parent_task",
        sa_relationship_kwargs={"foreign_keys": "[Task.parent_task_id]"},
    )
    parent_task: Optional["Task"] = jm_relationship(
        back_populates="subtasks",
        sa_relationship_kwargs={
            "foreign_keys": "[Task.parent_task_id]",
            "remote_side": "[Task.id]",
        },
    )

cd backend
python api_schema_gen.py

pip install -r requirements.txt
veloiq run               # http://localhost:8000

cd task-manager/frontend
npm install
npm run dev     # http://localhost:5173

from fastapi import Depends, HTTPException
from sqlmodel import Session

from veloiq_framework import get_session
from .api import router        # the auto-generated router
from .models import Task


@router.post("/{task_id}/complete")
def complete_task(task_id: int, session: Session = Depends(get_session)):
    task = session.get(Task, task_id)
    if task is None:
        raise HTTPException(404, f"Task {task_id} not found")
    task.status = "done"
    session.add(task)
    session.commit()
    session.refresh(task)
    return task.model_dump()

veloiq search add-model TeamMember --fields name,email
veloiq search add-model Project    --fields name,description
veloiq search add-model Task       --fields title,description

{
  "models": ["TeamMember", "Project", "Task"],
  "fields": ["name", "email", "description", "title"]
}

veloiq search list               # show current config
veloiq search add-field role     # add another field
veloiq search remove-model Project

# backend/app/main.py
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),
        # Add custom roles as needed:
        RoleDef("Auditor", READ_METHODS,  "External auditor — read only",      is_preset=True),
    ],
))

from veloiq_framework import TimestampedModel, jm_relationship, model_access

@model_access(Viewer=["list", "show"])
class Task(TimestampedModel, table=True):
    ...

from veloiq_framework import TimestampedModel, jm_relationship, veloiq_field

class Task(TimestampedModel, table=True):
    __tablename__ = "task"

    title: str
    status: str = "todo"

    # Only managers and admins can set work-hour estimates
    planned_work_hours: Optional[float] = veloiq_field(
        default=None, write_roles=["Admin", "Manager"]
    )
    # Actual hours logged — Admin-only write, everyone can read
    actual_work_hours: Optional[float] = veloiq_field(
        default=None, write_roles=["Admin", "Manager"]
    )

cd backend && python api_schema_gen.py

from veloiq_framework import TimestampedModel, jm_relationship, rebac

@rebac(owner_field="assignee_id")
class Task(TimestampedModel, table=True):
    __tablename__ = "task"

    assignee_id: Optional[int] = Field(default=None, foreign_key="team_member.id")
    ...

@rebac(tenant_field="tenant_id")
class Contract(TimestampedModel, table=True):
    tenant_id: int = Field(foreign_key="veloiq_tenant.id")

from veloiq_framework import rebac, rebac_subquery

@rebac(owner_field="owner_id")
class Project(TimestampedModel, table=True):
    owner_id: Optional[int] = Field(default=None, foreign_key="team_member.id")

@rebac(filter=lambda user, cls, session:
           cls.project_id.in_(rebac_subquery(Project, user, session)))
class Task(TimestampedModel, table=True):
    ...