Code generation ignores interface contracts: frontend/backend field and endpoint mismatches #427
Description
Bug Description
When generating a full-stack project (Next.js + FastAPI), the LLM code generation step produces frontend code that doesn't match the backend schemas and endpoints — even though the prompt files and architecture.json correctly specify the contracts.
Mismatches Found
1. User field names: username/full_name vs name
Prompt says: name: str, required (backend schema prompt) and { name: string } (frontend API prompt)
Backend generated: name field (correct)
Frontend generated: username + full_name fields (wrong)
Affected files:
frontend/lib/api.ts—UserCreateinterface hadusername+full_nameinstead ofnamefrontend/app/register/page.tsx— sends{ username: formData.email, full_name: formData.name }instead of{ name: formData.name }
2. Auth endpoint: /auth/login vs /auth/token
Prompt says: POST /api/auth/login (both backend and frontend prompts)
Architecture.json says: "path": "/api/auth/login"
Backend generated: /auth/login (correct)
Frontend generated: /auth/token in api.ts login function (wrong)
The LLM likely confused this with FastAPI's common OAuth2 example which uses /token.
3. User response type fields
Prompt says: UserResponse has id, email, name, xp, streak
Backend generated: correct fields
Frontend generated: User interface had username, full_name, created_at instead of name, xp, streak
4. API base URL convention (architectural gap)
Frontend API prompt: defaults to http://localhost:8000/api
Generated next.config.js: overrides env var to http://localhost:8000 (no /api suffix)
This causes all API calls to miss the /api prefix at runtime. There is no prompt file for next.config.js, so the LLM had no guidance on this convention.
Root Cause Analysis
The prompt files and architecture.json correctly specify the interface contracts (field names, endpoints, schemas). The issue is that the LLM ignores or deviates from these specifications during code generation, particularly for frontend files that reference backend contracts.
Mismatches 1-3 are LLM hallucinations. Mismatch 4 is a missing specification (no prompt for next.config.js).
Impact
These mismatches cause:
- Registration 422 errors (wrong field names sent to backend)
- Login 404 errors (wrong endpoint path)
- Runtime type mismatches (frontend expects fields that don't exist in API responses)
- All API calls fail (missing
/apiprefix)
The app is completely non-functional out of the box until all four are manually fixed.
Suggested Improvements
-
Post-generation validation: After generating all files, run a validation pass that checks generated code against the interface definitions in architecture.json — verify field names, endpoint paths, and type signatures match across frontend and backend.
-
Cross-file context injection: When generating frontend files that consume backend APIs, inject the actual generated backend schemas/routes as context, not just the prompt specs. This way the LLM sees the real code it needs to match.
-
Generate
next.config.jsfrom a prompt: Add a prompt file fornext.config.jsthat specifies theNEXT_PUBLIC_API_URLconvention explicitly, consistent with the frontend API client. -
Shared contract file: Consider generating a shared types/contract file (e.g., OpenAPI spec from FastAPI) that the frontend generation can reference directly.
Environment
- Project type: Full-stack (Next.js 14.1.0 + FastAPI + PostgreSQL)
- All prompt files in
prompts/directory were correctly specified - architecture.json had correct interface definitions