Full-Stack Development
Use for features that span both FastAPI backend and Next.js frontend.
Architecture
- Backend: FastAPI + Python 3.13+, TinyDB, LiteLLM
- Frontend: Next.js 16 + React 19, Tailwind CSS v4, Swiss International Style
- API: REST endpoints at
/api/v1/*
Workflow
1. Design the API contract first
Route: POST /api/v1/my-feature
Request: { field: string, ... }
Response: { id: string, result: ... }
2. Backend implementation
- Schema in
apps/backend/app/schemas/ - Service in
apps/backend/app/services/ - Router in
apps/backend/app/routers/ - Register router in
apps/backend/app/main.py
3. Frontend implementation
- API call in
apps/frontend/lib/ - Component in
apps/frontend/components/ - Page integration in
apps/frontend/app/
4. Verify end-to-end
- Backend serves correct data
- Frontend displays correctly with Swiss style
- Error states handled on both sides
Non-Negotiable Rules
Backend
- Type hints on all functions
copy.deepcopy() for mutable defaults- Log errors server-side, generic messages to clients
- API keys via
api_key= parameter
Frontend
- Swiss International Style (
rounded-none, hard shadows, Swiss palette) npm run lint && npm run format- Enter key handling on textareas
Promise.all() for independent fetches
Key Files
| Layer | Entry Point |
|---|
| Backend startup | apps/backend/app/main.py |
| Backend config | apps/backend/app/config.py |
| Frontend pages | apps/frontend/app/ |
| API client | apps/frontend/lib/ |
References
- API contracts:
docs/agent/apis/front-end-apis.md - Backend guide:
docs/agent/architecture/backend-guide.md - Frontend workflow:
docs/agent/architecture/frontend-workflow.md - Style guide:
docs/agent/design/style-guide.md
