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.
• GET /api/health exists and returns 200 {"status": "ok"} — the readiness probe of the launcher and the cloud runner.
• <artifact_path>/requirements.txt exists and lists at least fastapi, mangum, uvicorn — and never anton_state.
• Secrets are read from SECRETS[...] at their point of use inside routes — never copied into module-level variables at import time.
• Every DS_* name the code reads is copied verbatim from the Connected Data Sources section of the prompt; an invented name cannot be resolved at deploy time.
• Target Python >= 3.12 — the runtime the artifact is launched with.
• fullstack-stateless-app never imports anton_state; fullstack-stateful-app declares STATE = None and ships a valid state_manifest.json.

These are the same checks generate_artifact runs on its own output (see the ## Verifier contract of its backend generator); a hand-built backend gets no automatic check, so verify each item yourself before launch_backend.

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