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