scaffold

Scaffold

Generate boilerplate for new API endpoints and frontend pages in SerpentStack.

Adding a New API Endpoint

Given a resource name (e.g., projects), create the following files in order.

1. SQLAlchemy Model -- backend/app/models/{name}.py

Inherit from Base which provides id (UUID), created_at, and updated_at automatically.

import uuid

from sqlalchemy import Boolean, ForeignKey, String, Text
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column

from app.models.base import Base


class {Name}(Base):
    __tablename__ = "{name}s"

    title: Mapped[str] = mapped_column(String(255), nullable=False)
    description: Mapped[str | None] = mapped_column(Text, nullable=True)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True)

    # Owner — see Item model for the reference pattern
    user_id: Mapped[uuid.UUID | None] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=True,
        index=True,
    )

Register the model by adding to backend/app/models/__init__.py:

from app.models.{name} import {Name}

2. Pydantic Schemas -- backend/app/schemas/{name}.py

from datetime import datetime
from uuid import UUID

from pydantic import BaseModel


class {Name}Base(BaseModel):
    title: str
    description: str | None = None

class {Name}Create({Name}Base):
    pass

class {Name}Update(BaseModel):
    title: str | None = None
    description: str | None = None

class {Name}Response({Name}Base):
    id: UUID
    is_active: bool
    user_id: UUID | None
    created_at: datetime
    updated_at: datetime

    model_config = {"from_attributes": True}

class {Name}ListResponse(BaseModel):
    {name}s: list[{Name}Response]
    total: int
    skip: int
    limit: int

3. Service Layer -- backend/app/services/{name}.py

Uses async SQLAlchemy sessions. Services return None or domain values — they never raise HTTPException. Services flush but do not commit — the route layer owns the transaction boundary. This allows multiple service calls to be composed in a single transaction.