Skip to content

Your first module ​

A stage-by-stage walk-through: from uv run smpy create-module to a working Orders module with custom fields, validation, a menu entry, and a test.

Assumes you've completed the Quickstart and have an app on disk created by uv run smpy new.

1. Scaffold ​

bash
uv run smpy create-module orders --dest modules/orders

This creates modules/orders/ with working CRUD against a single-field Order table. Inside an app workspace it also adds simple_module_orders to host/pyproject.toml as a workspace source, runs uv sync --all-packages and npm install from the app root, then uv run smpy gen. The printed next step is a migration; applying it and restarting make dev finishes installation. In a flat app, wire the standalone module with uv run smpy add ./modules/orders, then run make install. See project structure.

New modules put shared settings and constants in core/, HTTP code in web/, and reusable frontend code in ui/. Root lookup paths (models.py, contracts/, pages/, locales/) stay fixed. Tests mirror tests/<area>/<feature>/, without __init__.py, with module-prefixed basenames and root conftest.py; JS tests stay in tests-js/. See Module layout.

2. Define your domain model ​

Edit modules/orders/orders/models.py:

python
from decimal import Decimal
from simple_module_db.base import create_module_base
from simple_module_db.mixins import AuditMixin, SoftDeleteMixin
from sqlmodel import Field

Base = create_module_base("orders")


class Order(Base, AuditMixin, SoftDeleteMixin, table=True):
    __tablename__ = "orders_order"

    id: int | None = Field(default=None, primary_key=True)
    customer_email: str = Field(max_length=200, index=True)
    total: Decimal = Field(max_digits=10, decimal_places=2)
    status: str = Field(default="pending", max_length=20)
  • AuditMixin adds created_at, updated_at, created_by, updated_by — populated automatically from the request user.
  • SoftDeleteMixin replaces DELETE with is_deleted=true. SELECT filters them out by default; pass include_deleted=True to bypass.
  • __tablename__ must be prefixed with the module name (orders_order) so it doesn't collide with other modules' tables — every module shares the host's single schema on both Postgres and SQLite.

3. Update the DTOs ​

Edit modules/orders/orders/contracts/schemas.py:

python
from decimal import Decimal
from datetime import datetime
from pydantic import ConfigDict
from sqlmodel import Field, SQLModel


class OrderCreate(SQLModel):
    customer_email: str = Field(min_length=1, max_length=200)
    total: Decimal = Field(ge=0)


class OrderUpdate(SQLModel):
    status: str | None = Field(default=None, max_length=20)


class OrderOut(SQLModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    customer_email: str
    total: Decimal
    status: str
    created_at: datetime

DTOs are plain SQLModel subclasses — not BaseModel and not table=True. They're the public surface other modules import from orders.contracts.

Length and range limits (min_length, max_length, ge, le) are enforced, but a format check is not. SQLModel's Field accepts regex= and silently ignores it, and it rejects pydantic's pattern= with a TypeError. Check formats with a field_validator, as tenants.contracts.TenantCreate does (the scaffold's _reject_explicit_null is the same mechanism). For example, to restrict status, give the OrderUpdate above a validator:

python
import re

from pydantic import field_validator

_STATUS_RE = re.compile(r"^[a-z_]{1,20}$")


class OrderUpdate(SQLModel):
    status: str | None = Field(default=None, max_length=20)

    @field_validator("status")
    @classmethod
    def _status_shape(cls, value: str | None) -> str | None:
        if value is not None and not _STATUS_RE.fullmatch(value):
            raise ValueError("status must be lowercase letters and underscores")
        return value

4. Generate a migration ​

bash
uv run smpy migrations new orders -m "add orders tables"

Open host/migrations/versions/XXXX_add_orders_tables.py and eyeball it (the CLI resolves the host config and keeps the app root as its working directory):

  • It should create the orders_order table.
  • The command creates a first root labelled orders, or selects orders@head for later revisions. The label does not isolate the module: alembic downgrade orders@base rolls back the whole chain beneath it, other modules included. See Removing one module's schema.

Apply:

bash
make migrate

5. Wire up service + endpoints ​

The scaffold already generated working CRUD. Trim it to match your domain or extend it:

python
# modules/orders/orders/web/service.py
from sqlalchemy.ext.asyncio import AsyncSession
from sqlmodel import select

from orders.contracts.schemas import OrderCreate, OrderOut, OrderUpdate
from orders.models import Order


class OrderService:
    def __init__(self, session: AsyncSession) -> None:
        self.session = session

    async def create(self, data: OrderCreate) -> OrderOut:
        order = Order(**data.model_dump())
        self.session.add(order)
        await self.session.flush()  # get the DB-assigned id
        return OrderOut.model_validate(order)

    async def list(self) -> list[OrderOut]:
        rows = (await self.session.exec(select(Order))).all()
        return [OrderOut.model_validate(r) for r in rows]

    async def update(self, order_id: int, data: OrderUpdate) -> OrderOut:
        order = await self.session.get(Order, order_id)
        if order is None:
            raise KeyError(order_id)
        for field, value in data.model_dump(exclude_none=True).items():
            setattr(order, field, value)
        await self.session.flush()
        return OrderOut.model_validate(order)

Note the absence of self.session.commit(). The per-request get_db dependency commits if (and only if) there were pending writes. See Session lifecycle.

6. Register permissions and menu ​

python
# modules/orders/orders/module.py
from simple_module_core.module import ModuleBase, ModuleMeta
from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
from simple_module_core.permissions import PermissionRegistry


class OrdersModule(ModuleBase):
    meta = ModuleMeta(
        name="Orders",
        route_prefix="/api/orders",
        view_prefix="/orders",
        version="0.1.0",
    )

    def register_permissions(self, registry: PermissionRegistry) -> None:
        registry.add_group(
            "Orders",
            [
                "orders.view",
                "orders.create",
                "orders.edit",
                "orders.delete",
            ],
        )

    def register_menu_items(self, registry: MenuRegistry) -> None:
        registry.add(
            MenuItem(
                section=MenuSection.SIDEBAR,
                label="Orders",
                url="/orders",
                icon="package",
                order=20,
                group="Content",
            )
        )
  • MenuItem takes label (the displayed string) and url (the link target). Translation is handled in the React layer via useT() — not on the menu definition. Pre-filter visibility via roles=[...] if the entry should only show for specific roles.
  • The default register_routes discovers the conventional API and view routers. route_prefix / view_prefix from ModuleMeta mount them at /api/orders and /orders; no route hook override is needed.

7. Enforce permissions on endpoints ​

python
# modules/orders/orders/web/endpoints/api.py
from fastapi import APIRouter, Depends
from simple_module_hosting.permissions import RequiresPermission

from orders.contracts.schemas import OrderCreate, OrderOut
from orders.web.deps import OrderServiceDep

router = APIRouter(tags=["orders"])


@router.get(
    "",
    dependencies=[Depends(RequiresPermission("orders.view"))],
)
async def list_orders(service: OrderServiceDep) -> list[OrderOut]:
    return await service.list()


@router.post(
    "",
    status_code=201,
    dependencies=[Depends(RequiresPermission("orders.create"))],
)
async def create_order(data: OrderCreate, service: OrderServiceDep) -> OrderOut:
    return await service.create(data)

RequiresPermission returns 401 if the request is unauthenticated and 403 if the resolved permissions (request.state.resolved_permissions, populated from the user's roles) don't include the required permission. A wildcard grant short-circuits the check.

8. Build the React page ​

pages/Browse.tsx was scaffolded — extend it:

tsx
import { keys, useT } from "@simple-module-py/i18n";
import { PageShell } from "@simple-module-py/ui/components/PageShell";
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@simple-module-py/ui/components/ui/table";
import type { OrderOut } from "../contracts";

export default function Browse({ orders }: { orders: OrderOut[] }) {
  const { t } = useT();
  return (
    <PageShell title={t(keys.orders.browse.title)}>
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>#</TableHead>
            <TableHead>{t(keys.orders.fields.customer)}</TableHead>
            <TableHead>{t(keys.orders.fields.total)}</TableHead>
            <TableHead>{t(keys.orders.fields.status)}</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {orders.map((order) => (
            <TableRow key={order.id}>
              <TableCell>{order.id}</TableCell>
              <TableCell>{order.customer_email}</TableCell>
              <TableCell>{order.total}</TableCell>
              <TableCell>{order.status}</TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </PageShell>
  );
}

Translations (orders/locales/en.json). keys.orders.* is generated from this file by uv run smpy gen, which make install, make build and uv run smpy dev run (direct dev boots also refresh keys), so a new key needs one of them before tsc sees it:

json
{
  "menu": { "orders": "Orders" },
  "browse": { "title": "Orders" },
  "fields": {
    "customer": "Customer",
    "total": "Total",
    "status": "Status"
  }
}

Keys flatten at boot: orders.menu.orders, orders.browse.title, etc. See Internationalization.

9. Write a test ​

python
# modules/orders/tests/web/crud/test_orders_crud.py
import pytest


@pytest.mark.asyncio
async def test_create_and_list_orders(authenticated_client):
    r = await authenticated_client.post(
        "/api/orders",
        json={"customer_email": "buyer@example.com", "total": "42.00"},
    )
    assert r.status_code == 201
    created = r.json()
    assert created["customer_email"] == "buyer@example.com"

    r = await authenticated_client.get("/api/orders")
    assert r.status_code == 200
    assert any(o["id"] == created["id"] for o in r.json())

The authenticated_client fixture from the simple_module_test plugin seeds an admin user and carries a signed session cookie. The db_session fixture creates all module tables and stamps the Alembic head so the boot-time migration check passes. See Fixtures.

Run:

bash
uv run pytest modules/orders/tests/ -v

10. Verify end-to-end ​

Restart make dev and visit http://localhost:8000/orders. The framework runs the full diagnostics suite at boot — any SM0XX errors will appear in the dev log (and in production, will fail boot before the server starts serving). If you see an SM003 or SM004, the Inertia key in views.py doesn't match the file you created in pages/ — see Pages & discovery and the full list of diagnostic codes.

Next steps ​

You've shipped a module. Pick the rabbit hole that matches what you need next:

Released under the MIT License.