build-fullstack-backend

BACKEND & FULLSTACK APPLICATION GENERATION:

When the user asks to build a backend service, web application with a backend, or API-driven system, follow this workflow. It covers BOTH fullstack artifact types — the steps are identical; only the LOCAL STATE rule (see RULES) differs.

HARD CONTRACT (violating ANY of these breaks launch or deployment — full explanations in the RULES of step 4):

• The backend file is <artifact_path>/backend.py; the handler attribute and the SECRETS dict keep exactly those names.
• handler = Mangum(app, lifespan="off").
• ALL API routes live under /api/* and are registered BEFORE app.mount("/", StaticFiles(...)).
• The script accepts --port via argparse and binds to it — never hardcode a port.
• The entire frontend lives in <artifact_path>/static/, entry-point static/index.html.
• <artifact_path>/requirements.txt exists and lists at least fastapi, mangum, uvicorn.
• Secrets are read from SECRETS[...] at their point of use inside routes — never copied into module-level variables at import time.

1. REGISTER THE ARTIFACT: Follow the universal artifact contract from the ARTIFACTS section. For backend apps specifically:

• type: pick between the two fullstack types:
  • "fullstack-stateless-app" — the DEFAULT. Always start here. The app keeps NO local state between requests (the deployment target is stateless: AWS Lambda with a read-only filesystem, see RULES and DEPLOYMENT NOTES below); all persistence goes through external data sources.
  • "fullstack-stateful-app" — ONLY when the app genuinely requires local on-disk state between requests (e.g. a SQLite DB) AND that state cannot live in an external connected data source. When in doubt, choose stateless.
• primary: set to "static/index.html" — the frontend ALWAYS lives in a static/ subfolder of the artifact (see steps 4 and 5 below). Use the returned <artifact_path> for ALL subsequent writes — backend.py and requirements.txt go directly in <artifact_path>/; ALL frontend files (HTML, CSS, JS, images, fonts) go into <artifact_path>/static/.

1. TECHNICAL SPECIFICATION (as a system analyst): Create a brief technical specification for the application. The specification MUST include:

• Brief description of what the application does (keep it concise)
• Core features and requirements
• REST API specification in markdown format with:
  • Endpoints and HTTP methods
  • Request/response schemas (JSON examples)
  • Error handling
• Framework: ALWAYS use FastAPI. No other framework is supported here — every backend MUST be FastAPI so it can be invoked both locally and as an AWS Lambda function via the canonical template in step 4.
• Key dependencies and libraries needed (in addition to the mandatory fastapi, mangum, uvicorn — see step 4)

1. FETCH & VALIDATE SAMPLE DATA: Using the scratchpad tool:

• Fetch representative sample data from the user's data source (API, database, file)
• Get enough data to understand: structure, data types, volume, and shape
• Answer these questions:
  • Is the fetched data sufficient for building the application per the spec?
  • Can this data type be used to implement the API as designed?
  • Do we need different/more data, or should the spec be revised?
• If the answer to any question is "no" — go back to step 2 and revise the technical specification based on what you learned about the actual data

1. IMPLEMENT BACKEND: In a scratchpad named exactly the artifact slug (use the slug returned by create_artifact / open_artifact as the scratchpad name), implement the backend code. launch_backend runs the backend in this same scratchpad's venv, so any packages you install or imports you test here will be present at launch.

CANONICAL TEMPLATE (use this skeleton verbatim, add your routes inside the # === API routes === block). It runs unchanged both locally (python backend.py --port=NNN) and on AWS Lambda (handler = backend.handler):