Scaffold Backend

This skill cannot run yet. AGENTS.md and PRD.md must exist at the repo root. Run the domain-to-spec skill first, or run the quickstart skill to chain everything automatically.

Do not create any files in either fail case.

Step 1: Read the PRD and AGENTS

Extract from PRD.md:

• Routes list (from PRD.md > Backend Routes). Each bullet becomes a FastAPI route.
• Data model (from PRD.md > Data Model). Each entity becomes a Pydantic model.
• Domain constraints (from PRD.md > Domain Constraints). Used to decide what validation rules to add.
• Auth requirement. Check if PRD.md > Core Features (MVP) or PRD.md > User Flow mention login, accounts, or user-specific data. If yes, Supabase Auth is needed.

Extract from AGENTS.md:

• The Python version and FastAPI conventions.
• Whether Supabase is listed under ## Tech Stack > Database.

Step 2: Ask About Supabase

Prompt the user:

"Your PRD implies this app needs a database. I recommend Supabase because it is free, hosted, and integrates auth, Postgres, and storage in one service. Should I wire it up now? (yes / no / later)"

• If yes: include Supabase integration in Step 4.
• If no: scaffold FastAPI only; use an in-memory Python dict as a placeholder store, with a clear TODO comment to swap it out later.
• If later: same as no.

Step 3: Scaffold server/

Create the following structure at the repo root:

server/
  app/
    __init__.py
    main.py                # FastAPI app entry point
    config.py              # Environment variable loader
    db.py                  # Supabase client or in-memory store
    models.py              # Pydantic models (from PRD Data Model)
    routes/
      __init__.py
      health.py            # GET /health
      <entity>.py          # One file per entity in the PRD (e.g. submissions.py)
  tests/
    __init__.py
    test_health.py
  .env.example
  .gitignore
  requirements.txt
  README.md

Step 4: Generate requirements.txt

Always include:

fastapi>=0.115
uvicorn[standard]>=0.32
pydantic>=2.9
pydantic-settings>=2.6
python-dotenv>=1.0
pytest>=8.3
httpx>=0.27

If Supabase was chosen, also include:

supabase>=2.9

Step 5: Generate main.py

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from app.routes import health
# Import one route module per entity in PRD > Backend Routes
# Example: from app.routes import submissions

app = FastAPI(title="{project name from PRD}")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

app.include_router(health.router)
# app.include_router(submissions.router, prefix="/submissions", tags=["submissions"])

Replace {project name from PRD} with the one-sentence summary's subject. Uncomment and add one include_router call per entity found in PRD.md > Backend Routes.

Step 6: Generate Pydantic Models From the Data Model

For each entity in PRD.md > Data Model, create a class in app/models.py:

from datetime import datetime
from typing import Literal
from pydantic import BaseModel, Field

class SubmissionBase(BaseModel):
    patient_name: str = Field(..., min_length=1)
    date: datetime
    medications: list[str]

class SubmissionCreate(SubmissionBase):
    pass

class Submission(SubmissionBase):
    id: str
    status: Literal["pending", "approved", "rejected"] = "pending"

Always generate a Base, a Create, and a full model per entity. This pattern gives you clean request/response separation.

Step 7: Generate Route Stubs From PRD.md > Backend Routes

For each bullet under PRD.md > Backend Routes, generate a FastAPI route. Example input:

- POST /submissions — create a new submission from the form
- GET /submissions — list the current user's submissions
- GET /submissions/{id} — fetch one submission
- POST /submissions/{id}/approve — mark a submission as approved

Generated app/routes/submissions.py:

from fastapi import APIRouter, HTTPException
from uuid import uuid4

from app.models import Submission, SubmissionCreate
from app.db import store

router = APIRouter()

@router.post("", response_model=Submission)
def create_submission(payload: SubmissionCreate) -> Submission:
    submission = Submission(id=str(uuid4()), **payload.model_dump())
    store.setdefault("submissions", {})[submission.id] = submission
    return submission

@router.get("", response_model=list[Submission])
def list_submissions() -> list[Submission]:
    return list(store.get("submissions", {}).values())

@router.get("/{submission_id}", response_model=Submission)
def get_submission(submission_id: str) -> Submission:
    submission = store.get("submissions", {}).get(submission_id)
    if submission is None:
        raise HTTPException(status_code=404, detail="Submission not found")
    return submission

@router.post("/{submission_id}/approve", response_model=Submission)
def approve_submission(submission_id: str) -> Submission:
    submission = store.get("submissions", {}).get(submission_id)
    if submission is None:
        raise HTTPException(status_code=404, detail="Submission not found")
    submission = submission.model_copy(update={"status": "approved"})
    store["submissions"][submission_id] = submission
    return submission

Every route should return dummy but type-safe data so the frontend has something to consume immediately.

Step 8: Generate db.py

If Supabase was chosen

from supabase import create_client, Client
from app.config import settings