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