Draft the schema.
Ship the API.

Startup MVPs

Turn one schema file into a running API in minutes, before the idea gets cold.

Internal tools

Every project gets the same models, migrations, services, and routes — no drift between teams.

Learning FastAPI

Read a clean, layered architecture: repository → service → controller → route, generated in the open.

Multi-database apps

Pick SQLite, PostgreSQL, MySQL, or MongoDB at build time. Switch later with one command.

Schema-first generation

Edit schema.tpy, run tpy build or tpy crud, and get models, migrations, schemas, repositories, services, controllers, and routes.

Multi-database

SQLite, PostgreSQL, MySQL, or MongoDB via the build wizard. Reconfigure anytime with tpy db configure.

Auto database create

tpy migrate creates the Postgres/MySQL database when missing, then applies ordered migrations.

Full CRUD REST API

Each model gets list, show, create, update, and delete endpoints under a plural prefix (e.g. /users).

Layered architecture

Repository → Service → Controller → Route — generated consistently so every project looks the same.

Migrate · seed · serve

Apply schema with migrations, load sample data with seeders, run the API with tpy serve or python main.py.

Logging & health

Console + storage/logs/app.log via app/logger.py. Probe liveness with GET /health.

React admin dashboard

tpy admin generates a Vite + React dashboard in admin/ with list, create, edit, and delete for every schema model. See screenshots →

JWT auth

tpy auth adds login, register, refresh, and logout with AuthRole + User defaults. Dashboard access is limited to super-admin and developer. See auth guide →

Doctor & DB tools

tpy doctor checks project files. tpy db info / tpy db ping inspect and test the connection.

From one schema

src/data/models.js is built from schema.tpy. Shared list and form pages cover every model — no hand-written page per entity.

Vite + React

Modern SPA under admin/ with Layout, DataTable, and RecordForm components wired to your FastAPI CRUD routes.

Re-run anytime

After schema changes, run tpy admin again to regenerate the dashboard so the UI stays in sync with your models. With tpy auth enabled, the UI includes login and role checks.

Default tables

• AuthRole — super-admin, admin, developer
• User — name, email, password (hashed), role_id

Auth endpoints

• POST /auth/register
• POST /auth/login — access + refresh
• POST /auth/refresh
• POST /auth/logout
• GET /auth/me

Dashboard access

super-admin and developer can open the React admin UI. The admin role is API-only.

Access + refresh

Short-lived access JWT (default 15m) plus long-lived refresh JWT (default 7d). Logout revokes the refresh token server-side.

File structure

# optional provider line
database postgres

model ModelName {
  field: type constraint...
}

Use # for comments. Keywords are case-insensitive.

Field types

• int — integer
• string — text / VARCHAR
• float — floating point
• bool — boolean
• uuid — UUID primary keys
• datetime — timestamp

Field constraints

• primary — primary key
• required — required in create API
• unique — UNIQUE column
• nullable — allow NULL / optional
• index — create an index
• default <value> — column default
• references <Model> — foreign key

Non-primary fields without nullable become NOT NULL in SQL.

database line

• database sqlite
• database postgres
• database mysql
• database mongodb

Usually written for you by tpy build / tpy db configure.

Foreign keys

Use references <Model> (or foreign <Model>) on a field. It defaults to the target's id; target a column with references Model.column.

user_id: uuid references User
author: uuid references User.id

Compiles to REFERENCES "user" ("id"). Define the referenced model earlier in the schema so its migration runs first.

Default values

Add default <value> — a number, quoted string, or true / false.

stock: int default 0
active: bool default true
status: string default "draft"

Fields with a default become optional in the create API.

Column index

Add the index keyword to generate an index:

title: string required index

Emits CREATE INDEX idx_<table>_<column>. Primary keys are already indexed.

File naming

Generated as ordered files from model order in the schema:

• 001_user_migration.py
• 002_post_migration.py

Routes from a model

Model User → prefix /users:

• GET /users/
• GET /users/{id}
• POST /users/
• PUT /users/{id}
• DELETE /users/{id}

Scaffold & generate

• tpy new <name> — create project
• tpy build — DB wizard + generate CRUD
• tpy build --skip-db — generate using existing .env
• tpy build --with-ui — generate CRUD and admin/
• tpy crud — regenerate layers from schema only
• tpy admin — generate the React admin dashboard
• tpy auth — JWT auth, AuthRole + User, role seeds
• tpy doctor — validate project files
• tpy version — show framework version

Configure & inspect

• tpy db configure — interactive DB wizard
• tpy db info — show provider + URL
• tpy db ping — test connection

Schema apply

• tpy migrate — create DB if needed + apply pending
• tpy migrate up — same as migrate
• tpy migrate rollback — undo latest
• tpy migrate status — list applied migrations
• tpy seed — run database/seeds

Serve the API

• tpy serve — uvicorn on app.main:app
• tpy serve --host 0.0.0.0
• tpy serve --port 8080
• tpy serve --reload / --no-reload
• python main.py — root launcher
• GET /health — health check

Project

• tpy new <name> — create project
• tpy build — DB wizard + generate CRUD
• tpy build --skip-db — use existing .env
• tpy crud — regenerate CRUD from schema
• tpy admin — generate React admin UI
• tpy auth — enable JWT auth
• tpy doctor — validate project health

Database

• tpy db configure — change DB anytime
• tpy db info — show provider + URL
• tpy db ping — test connection
• tpy migrate — create DB if needed + migrate
• tpy migrate rollback — undo latest
• tpy migrate status — list applied
• tpy seed — run database/seeds

Runtime

• tpy serve — start API server
• python main.py — root launcher
• app/logger.py — client logger
• storage/logs/app.log — log file
• /health — health endpoint
• /docs — Swagger UI

Example schema

model User {
  id: uuid primary
  name: string required
  email: string unique
  age: int
}

More patterns → Schema section