Docs / Guides / Schema-first generation

Feature 01 · Study guide

Schema-first generation

Learn how one schema.tpy file becomes a full FastAPI stack — and how to run that workflow yourself.

← All guides Install tamilPY
What you will learn
  • What schema-first means in tamilPY
  • How to write schema.tpy and regenerate safely
  • Which files are created and what each layer does

1. Why schema-first?

In a normal FastAPI project you write models, Pydantic schemas, SQL, repositories, services, controllers, and routes by hand — for every entity. tamilPY flips that: you describe the domain once in schema.tpy, then generators produce a consistent layered app.

That gives clients a predictable project shape, faster MVPs, and fewer copy-paste bugs.

2. Setup (first time)

  1. Install: pip install tamilPY (Python 3.12+).
  2. Scaffold: tpy new myapp then cd myapp.
  3. Open schema.tpy and define your models.
  4. Run tpy build (DB wizard + generate) or tpy build --skip-db if .env already exists.
  5. Apply DB: tpy migrate, optionally tpy seed.
  6. Serve: tpy serve and open /docs.
$ pip install tamilPY
$ tpy new myapp && cd myapp
$ # edit schema.tpy
$ tpy build
$ tpy migrate && tpy seed
$ tpy serve

3. How generation works

When you run tpy build / tpy crud:

  1. The parser reads schema.tpy into an AST (models, fields, relations).
  2. Generators fill Jinja templates with that context.
  3. Files are written under app/ and database/migrations/.
  4. Routers are wired so FastAPI exposes REST endpoints.
You edit the schema as the source of truth. Regenerating refreshes generated layers from that schema.

4. Write a real schema

database sqlite

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

model Post {
  id: uuid primary
  title: string required index
  body: string nullable
  user_id: uuid references User on_delete cascade
  published: bool default false
  relations {
    belongs_to User as author via user_id
  }
}

5. What gets generated

LayerPathResponsibility
Modelapp/models/Field shape
Migrationdatabase/migrations/Create/alter tables
Schemaapp/schemas/Create / Update / Response DTOs
Repositoryapp/repositories/DB access + query()
Serviceapp/services/Business use-cases
Controllerapp/controllers/HTTP → service
Routeapp/routes/FastAPI router

6. After you change the schema

  1. Save schema.tpy.
  2. Run tpy crud (or tpy watch in another terminal).
  3. Run tpy migrate if tables/columns changed.
  4. Restart or rely on tpy serve --reload.

7. Common mistakes

  • Editing only generated files and expecting them to survive the next tpy crud — put durable logic in services carefully.
  • Referencing a model that is defined later — put parents first so migrations order correctly.
  • Forgetting tpy migrate after adding fields.
NextMulti-database