Cursor-Driven Development in FastAPI: Using AI to Generate Type-Safe API Schemas and Catch Contract Breaks Before Deployment

A developer at CitizenApp built a system using Claude AI to generate both FastAPI backend schemas and TypeScript frontend types from natural language specifications, preventing API contract mismatches that previously caused production crashes and lost customer trust. The approach treats a single markdown specification file as the source of truth, with AI generating Pydantic models and TypeScript types that are validated against each other in CI before deployment. This method caught a type mismatch between a React 19 frontend expecting `{ id: string; email: string }` and a FastAPI backend returning `{ userId: number; userEmail: string }` before it reached production.

API contracts break silently. Your React 19 frontend calls POST /users expecting { id: string; email: string } , but your FastAPI backend shipped { userId: number; userEmail: string } . The request succeeds. The response doesn't match. Your frontend crashes in production, and you spend three hours in an incident call figuring out why a perfectly typed TypeScript component is receiving undefined properties. I've lived this exact nightmare twice on CitizenApp—once before we shipped, once after. The second time cost us a customer's trust and three hours of developer velocity. The fix isn't better testing or more code review. It's treating your API contract as the single source of truth and using Claude to generate both sides of it from natural language specifications, then validating that they match in CI before deployment. This is cursor-driven development done right: not mindless boilerplate generation, but intelligent contract enforcement that catches type mismatches across language boundaries. Most full-stack developers reach for AI to generate TypeScript components or FastAPI route handlers. That's fine. But the real power is forcing your frontend and backend to negotiate a contract before either side exists. When you do this correctly: I prefer this approach because it forces discipline. Too many teams use AI as a shortcut to avoid thinking about their API design. This pattern does the opposite: it requires you to think first, validate second. Here's how it works on CitizenApp: Let's build this end-to-end. Feature: User Profile Update Description: Allow authenticated users to update their profile metadata. Fields: firstName string, required , lastName string, required , bio string, optional, max 500 chars Validation: firstName and lastName must be at least 2 characters Response: Returns updated user object with id, email, firstName, lastName, bio, updatedAt Auth: Requires valid JWT in Authorization header This goes in a file: specs/user-profile-update.md Prompt your Cursor AI agent or use Anthropic's API directly : Given this spec, generate a FastAPI route with Pydantic schema. Use SQLAlchemy ORM patterns. Include validation decorators. Output ONLY Python code, no explanation. paste spec here Claude outputs something like: python schemas.py from pydantic import BaseModel, Field, field validator class UserProfileUpdateRequest BaseModel : firstName: str = Field ..., min length=2, max length=100 lastName: str = Field ..., min length=2, max length=100 bio: str | None = Field None, max length=500 @field validator "firstName", "lastName" @classmethod def validate names cls, v : return v.strip class UserProfileResponse BaseModel : id: str email: str firstName: str lastName: str bio: str | None updatedAt: str ISO 8601 class Config: from attributes = True python routes.py from fastapi import APIRouter, Depends, HTTPException from sqlalchemy.orm import Session from .schemas import UserProfileUpdateRequest, UserProfileResponse from .db import get db from .auth import get current user router = APIRouter @router.put "/users/profile", response model=UserProfileResponse async def update user profile request: UserProfileUpdateRequest, current user = Depends get current user , db: Session = Depends get db , : user = db.query User .filter User.id == current user.id .first if not user: raise HTTPException status code=404, detail="User not found" user.firstName = request.firstName user.lastName = request.lastName if request.bio is not None: user.bio = request.bio db.commit db.refresh user return user You review this, tweak it if needed, and commit it. This is now your source of truth. Different prompt: Given this API spec and the Pydantic schemas below, generate: 1. TypeScript types matching the schemas use zod or ts-pattern if validation needed 2. A React 19 hook using useAsync or similar pattern Use TanStack Query for mutations if appropriate. Assume JWT is in Authorization header handled by interceptor . Pydantic schema: paste schema here API spec: paste spec here Claude outputs: // types/user.ts export interface UserProfileUpdateRequest { firstName: string; lastName: string; bio?: string; } export interface UserProfileResponse { id: string; email: string; firstName: string; lastName: string; bio?: string; updatedAt: string; } js // hooks/useUpdateUserProfile.ts import { useMutation, useQueryClient } from "@tanstack/react-query"; export function useUpdateUserProfile { const queryClient = useQueryClient ; return useMutation { mutationFn: async data: UserProfileUpdateRequest : Promise<UserProfileResponse = { const response = await fetch "/api/users/profile", { method: "PUT", headers: { "Content-Type": "application/json", Authorization: Bearer ${localStorage.getItem "token" } , }, body: JSON.stringify data , } ; if response.ok { throw new Error Failed to update profile: ${response.statusText} ; } return response.json ; }, onSuccess: data = { queryClient.setQueryData "user" , data ; }, } ; } This is where the magic happens. Create a Python script that introspects both: python scripts/validate contracts.py import json import subprocess import sys from typing import Any def get pydantic schema module path: str, class name: str - dict str, Any : """Extract JSON schema from Pydantic model""" import importlib.util spec = importlib.util.spec from file location "module", module path module = importlib.util.module from spec spec spec.loader.exec module module model class = getattr module, class name return model class.model json schema def get typescript types file path: str - dict str, Any : """Parse TypeScript types using TypeScript compiler API""" result = subprocess.run "npx", "ts-json-schema-generator", "--path", file path, "--type", " " , capture output=True, text=True, return json.loads result.stdout def validate contract python schema: dict, ts schema: dict - bool: """Ensure Python and TypeScript schemas match""" py props = python schema.get "properties", {} ts props = ts schema.get "properties", {} Check all Python props exist in TypeScript for key, py prop in py props.items : if key not in ts props: print f"❌ Missing in TypeScript: {key}" return False Map Python types to TypeScript py type = py prop.get "type" ts type = ts props key .get "type" if py type = ts type: print f"❌ Type mismatch for {key}: Python={py type}, TS={ts type}" return False return True if name == " main ": py schema = get pydantic schema "app/schemas.py", "UserProfileUpdateRequest" ts schema = get typescript types "src/types/user.ts" if not validate contract py schema, ts schema : sys.exit 1 print "✅ Contract validated" Add this to your GitHub Actions workflow: - name: Validate API contracts run: python scripts/validate contracts.py - name: Run tests run: pytest app/ && npm test Now, if someone changes a Pydantic field from str to int without updating the TypeScript type, the build fails before merging . This has saved us countless production incidents. This burned me hard: I made a field optional in Pydantic bio: str | None but forgot to mark it optional in TypeScript bio: string instead of bio?: string . The validation passed because my naive script only checked required fields. The fix: validate both presence and optionality: php python def validate contract python schema: dict, ts schema: dict - bool: py required = set python schema.get