pre-alpha

Tutorial

8. Projects and apps

implemented Updated November 20, 2026 3 min read

An app is a package with its own models, migrations and routes, registered in hinoki.toml. This chapter adds a billing app to the notes project from the Quick start.

Create the app

From the project root:

uv run hinoki app create
Prompt Default Answer
App name billing
URL prefix /billing /billing
Depends on (none)

The command writes the package and registers it:

notes/apps/billing/
├── api.py         endpoints of the app
├── routes.py      the list of routes served, mounted at the prefix
├── models.py      tables of the app
└── migrations/    migration history
[[apps]]
name = "billing"
models = "notes.apps.billing.models"
migrations = "notes.apps.billing.migrations"
routes = "notes.apps.billing.routes:routes"
prefix = "/billing"
requires = []

Hinoki reads apps only from hinoki.toml; it never scans installed packages. If billing later references a model of another app, list that app in requires: migrations then run in dependency order.

Add a model

# notes/apps/billing/models.py
from datetime import datetime
from uuid import UUID, uuid4

from hinoki import db
from hinoki.orm import Model, field, pk
from hinoki.utils import utc_now


@db.ordered_by("-created_at")
class Invoice(Model):
    id: UUID = pk(default_factory=uuid4)
    reference: str = field(max_length=40, unique=True)
    paid: bool = False
    created_at: datetime = field(default_factory=utc_now, index=True)

The table name is derived: billing_invoices, the app followed by the plural model name. @db.table("billing_invoices") pins it, so renaming the class keeps the physical name; the model rules below ask for it.

Plan and apply the migration

uv run hinoki migrations plan billing
uv run hinoki migrations apply
database: sqlite:///…/notes/.hinoki/local.sqlite3 (from local SQLite default)
create table billing_invoices
wrote …/notes/apps/billing/migrations/0001-create-table-billing-invoices.sql
database: sqlite:///…/notes/.hinoki/local.sqlite3 (from local SQLite default)
notes: nothing to apply
billing: 0001-create-table-billing-invoices

plan compares the models with the recorded migration state and writes the next migration; the number and the slug come from the change. Review the .sql file before you apply it. With more than one app, plan needs the app name; apply runs every app in dependency order.

Where the data goes

apply uses the application's database setting, so the variable that configures the server, such as NOTES_DATABASE__URL, also configures the migrations; plan, status and apply print the database they chose. With no database configured, apply creates .hinoki/local.sqlite3 beside hinoki.toml. HINOKI_DATABASE_URL overrides the setting for one run. If the application cannot be loaded, the commands stop (exit 2) instead of guessing. Migrations never run when the application starts.

Check the project

uv run hinoki check
uv run pytest
8 rule(s): 0 violated, 0 unverifiable, 0 waived

notes/rules.py keeps two model rules commented out: Models.require_explicit_table and Models.require_foreign_key_index. hinoki check sees only the models the application imports, and a model rule that matches no model is unverifiable, which fails the check. Turn them on (and import Models) once a billing route imports Invoice; then add @db.table("billing_invoices") above the class, or the check reports:

notes/apps/billing/models.py:10: HNK-DB-001 [violated] Invoice uses the derived table name 'billing_invoices'
  fix: name the table with @db.table(...) or table=... on the model

Pinning the derived name changes no table: migrations plan billing then reports no changes.

Endpoints for billing go in notes/apps/billing/api.py, and routes.py lists them. The application in notes/main.py includes every app's list with manifest_routes(), which mounts this one at /billing, so paths inside the app never repeat the prefix:

# notes/main.py (as hinoki new wrote it)
from hinoki import Hinoki
from hinoki.project import manifest_routes

from notes.rules import project_rules
from notes.settings import ProjectSettings

app = Hinoki(
    settings=ProjectSettings,  # NOTES_* variables and .env
    include=manifest_routes(),  # notes/routes.py, then each app's routes at its prefix
    title="Notes",
    openapi_url="/openapi.json",
    docs_url="/docs",
    rules=project_rules,
)

The project's rules require every action to name an Access policy with permissions; build one as in chapter 4.

Recap

  • hinoki app create writes an app and registers it in hinoki.toml.
  • Table names, migration numbers and slugs are derived; you review the SQL.
  • The manifest sets each app's prefix; code never repeats it.