Skip to content

Feature Scaffolding (/feature-scaffold) — fastapi

Stack flavor: fastapi. ← Back to overview

[!NOTE] Use this when creating anything new in the codebase — a feature, page, module, component, API endpoint, or entity that doesn't already exist. For extending an existing page, use /full-stack-extension instead.

Trigger Conditions

  • Any request to create, build, add, implement, or introduce new functionality
  • Keywords: "Create a new page", "Build a feature", "Add a module for X", "New view", "New endpoint", "Add a section", "Implement X", "I need a new...", "Set up...", "Make a..."
  • Also trigger when: the user describes desired behavior that doesn't map to any existing code

1. Planning

  • [ ] Architecture Check: Review docs/ARCHITECTURE.md for directory structure and naming conventions
  • [ ] Schema: Does this feature need new DB tables? If yes, run /db-migration first
  • [ ] OpenAPI: After backend changes, run /openapi-sync to regenerate frontend types

2. Backend Scaffold

  • [ ] Model: Add or update a SQLModel model in backend/app/models/[feature].py
  • [ ] Schema: Create Pydantic request/response schemas in backend/app/schemas/[feature].py
  • [ ] Router: Create route handlers in backend/app/api/[feature].py
from fastapi import APIRouter, Depends, HTTPException
from app.core.auth import require_auth, require_permission

router = APIRouter(prefix="/[feature]", tags=["[feature]"])

@router.get("/")
async def list_features(user=Depends(require_auth)):
    # Query logic here
    return data
  • [ ] Registration: Register the router in backend/app/api/__init__.py (or the main router file)
  • [ ] Migration: If schema changed, run Alembic: alembic revision --autogenerate -m "add [feature]" then alembic upgrade head
  • [ ] Validation: All inputs validated via Pydantic v2 schemas

3. Frontend Scaffold

  • [ ] Types: Run /openapi-sync — never manually define types that exist in @/types/api
  • [ ] Query/Mutation: Add TanStack Query hooks in frontend/src/hooks/use[Feature].ts: 
    export function useFeature() {
    const query = useQuery({
        queryKey: ['[feature]'],
        queryFn: () => apiRequest('/api/[feature]'),
    });

    const createMutation = useMutation({
        mutationFn: (data: CreateFeatureInput) => apiRequest('/api/[feature]', { method: 'POST', body: data }),
        onSuccess: () => {
            queryClient.invalidateQueries({ queryKey: ['[feature]'] });
        },
    });

    return {
        features: query.data || [],
        isLoading: query.isLoading,
        createFeature: createMutation.mutateAsync,
    };
}
  • [ ] Component: Create React page/components under frontend/src/app/ or frontend/src/components/
  • No window.alert() or window.confirm()
  • Use <FormattedCurrency /> for money, formatDateLocal() for dates
  • Empty states: never blank — use illustration or helpful text
  • Loading states: shimmer (animate-pulse on gray blocks)
  • [ ] Routing: Register the new page in the app router
  • [ ] Networking: All API calls must use apiRequest from @/lib/queryClient

4. Security

  • [ ] Auth: Every admin/protected route must declare require_auth and require_permission dependencies
  • [ ] Validation: Backend uses Pydantic v2; frontend uses Zod + React Hook Form

5. Tests (REQUIRED)

  • [ ] Run /test-sync to automatically create tests for all new/changed files
  • [ ] Verify: All tests pass before proceeding to verification

6. Verification

  • [ ] Integration: Frontend calls backend — verify in browser network tab
  • [ ] Design: Run /architecture-review to verify UI compliance
  • [ ] Types: Run cd frontend && npm run type-check && cd ../backend && python -m mypy app/