Backend Development Use when creating or modifying FastAPI endpoints, Pydantic schemas, database operations, LLM integrations, or Python service logic. Before Writing Code Read docs/agent/architecture/backend-guide.md for architecture Read docs/agent/apis/front-end-apis.md for API contracts Read docs/agent/llm-integration.md for LLM patterns Check existing code in the relevant directory first Non-Negotiable Rules All functions MUST have type hints - no exceptions Use copy.deepcopy() for mutable defaults Log detailed errors server-side , return generic messages to clients Use asyncio.Lock() for shared resource initialization Pass API keys directly to litellm via api_key= , never os.environ Project Structure apps/backend/app/ ├── main.py # FastAPI app, CORS, lifespan, routers ├── config.py # Pydantic BaseSettings from env ├── database.py # TinyDB wrapper (JSON file storage) ├── llm.py # LiteLLM wrapper (multi-provider) ├── routers/ # API endpoint handlers ├── services/ # Business logic layer ├── schemas/ # Pydantic request/response models └── prompts/ # LLM prompt templates (Jinja2) Patterns New Endpoint from fastapi import APIRouter , HTTPException from app . schemas . my_schema import MyRequest , MyResponse import logging logger = logging . getLogger ( name ) router = APIRouter ( prefix = "/api/v1" , tags = [ "my-feature" ] ) @router . post ( "/my-endpoint" , response_model = MyResponse ) async def create_thing ( request : MyRequest ) -

MyResponse : try : result = await process_data ( request ) return result except Exception as e : logger . error ( f"Failed to create thing: { e } " ) raise HTTPException ( status_code = 500 , detail = "Operation failed. Please try again." ) New Schema from pydantic import BaseModel , Field class MyRequest ( BaseModel ) : name : str = Field ( . . . , min_length = 1 , max_length = 200 ) description : str | None = None class MyResponse ( BaseModel ) : id : str name : str status : str = "created" Database Operation import copy from app . database import get_db DEFAULT_DATA = { "sections" : [ ] , "metadata" : { } } async def get_or_create ( doc_id : str ) -

dict : db = get_db ( ) existing = db . get ( doc_id ) if existing : return existing data = copy . deepcopy ( DEFAULT_DATA )

ALWAYS deepcopy mutable defaults

db . insert ( data ) return data LLM Call from app . llm import get_completion from app . config import settings async def improve_text ( text : str ) -

str : prompt = f"Improve this resume text:\n\n { text } " result = await get_completion ( prompt = prompt , model = settings . LLM_MODEL , api_key = settings . LLM_API_KEY ,

Pass directly, not via env

json_mode

True , ) return result Error Handling Pattern except Exception as e : logger . error ( f"Operation failed: { e } " )

Detailed for server logs

raise HTTPException ( status_code = 500 , detail = "Operation failed. Please try again."

Generic for client

) Checklist All functions have type hints Mutable defaults use copy.deepcopy() Error handling logs details, returns generic messages New endpoints registered in main.py router includes Schemas defined for all request/response bodies API keys passed via api_key= parameter