building-fastapi-backend

name	building-fastapi-backend
description	Builds the FastAPI backend, typed schemas, ADK integration, and Cloud Run-ready APIs, and is used when the project needs the server-side foundation for the story system.

Builds the simplest reliable backend for the multi-agent story pipeline.

Use this skill when

• The backend needs to be created or refactored.
• FastAPI routes and Pydantic schemas must be added.
• Google ADK agents need a clean server entry point.
• The app must be deployable to Cloud Run.

Capabilities

• Scaffolds a minimal FastAPI app.
• Designs the three MVP endpoints:
  • POST /story/start
  • POST /story/continue
  • GET /health
• Uses Pydantic schemas for all request/response and agent contracts.
• Connects the Showrunner Orchestrator to ADK agents.
• Keeps state handling simple for Cloud Run.
• Adds CORS, environment loading, and error handling.
• Explains architecture choices in plain language for a non-technical PM.

Recommended simple architecture

Use the browser as the main carrier of session state for MVP.

Why:

• Cloud Run instances are temporary.
• In-memory server sessions can disappear between requests.
• Returning session_state to the frontend after every call is simpler and safer than adding a database.

Workflow

1. Explain the plan simply. Example: "The backend is the traffic controller. It receives user input, runs the agent pipeline, and sends back the next scene."
2. Create the FastAPI app skeleton.
   • backend/api/
   • backend/schemas/
   • backend/services/
   • backend/agents/
3. Define Pydantic models for:
   • story start request
   • story continue request
   • session state
   • scene package
   • agent outputs
4. Build the orchestrator service. Keep orchestration logic in services, not inside route files.
5. Wire the API routes. Keep them thin.
6. Add CORS and env config. Never hardcode keys.
7. Add GET /health. Judges and deployment checks need a fast proof endpoint.
8. Return typed responses that the React frontend can render directly.
9. Test locally with curl, browser dev tools, or a simple API client.

Suggested file layout

• backend/api/routes/story.py
• backend/api/routes/health.py
• backend/schemas/story.py
• backend/schemas/agents.py
• backend/services/orchestrator.py
• backend/agents/ for ADK wrappers and prompts

Example API shape

{
  "scene": {
    "scene_id": "scene_A1",
    "anchor": "A1",
    "panels": []
  },
  "choices": [],
  "session_state": {
    "current_anchor": "A1",
    "hidden_state": {
      "courage": 0,
      "compassion": 1,
      "truth": 0,
      "attachment": 1,
      "self_trust": 0
    }
  },
  "fallbacks": {
    "voice_available": true,
    "motion_available": true
  }
}

Guardrails

• No database for MVP.
• No extra endpoints unless they directly support the demo.
• Keep business logic out of route handlers.
• Every agent contract should be typed and validated.

Project references

• AGENTS.md — stack choice, route rules, schema rules, Cloud Run requirements, no database rule.
• docs/PRD.md — multi-agent pipeline and product experience that the backend must serve.
• docs/roadmap.md — MVP infrastructure and submission expectations.