Backends for Agent-Built Apps: pick a shape, write the contract, keep the data safe

Search this repo for any code that hashes passwords, creates or checks session tokens, sends reset links or stores sign-in state. List each file and line.
For each, say which part of the named library [library] should replace it. Do not change code yet.

Agents often write sign-in by hand when no library is named.

Review the webhook handler at [path]. Does it verify the signature before reading the body, store the event id, return early on a repeat, and move slow work to a job?
Fix what is missing, then write a test that sends the same event twice and checks one record changed.

Outside services retry. Your handler has to be safe to run twice.

# Backends for Agent-Built Apps: pick a shape, write the contract, keep the data safe

A PaperChaseWebb teaching guide, version 1.0. Written for Claude Code, Codex and Cursor, and plain Markdown, so the contract file, the rules block and the prompts work in any coding agent.

Coding agents are quick at the screen and careless with the server. Left alone, they reach for whatever they saw most often, invent their own sign-in code, change the database in place, and put a secret where the browser can read it. None of that shows up in a demo. It shows up the week real people start using the app.

This guide teaches the backend side in plain words. You pick one of five backend shapes with six questions, write a short BACKEND.md the agent must follow, and work through the parts that break most often: data and migrations, sign-in and access rules, secrets, webhooks, background jobs, free tier limits and watching the live system. Each part ends with the check that proves it holds.

It comes from our own builds plus public reports we read, checked and rebuilt in our own words. Sources are credited by link in Section 12.

## What is inside

| Section | What it is for |
|---|---|
| 1. What a backend does | The six jobs, in plain words, so you know what you are choosing |
| 2. Five backend shapes | Hosted database service, functions plus a managed database, edge workers, one small server, local first |
| 3. Pick with six questions | A short decision sheet that points to one shape |
| 4. BACKEND.md | The contract file your agent reads before touching the server |
| 5. Data and migrations | Schema changes the agent can make without losing rows |
| 6. Sign-in and access rules | Use a proven sign-in library and default-deny access |
| 7. Secrets | Where keys live and how to catch one in the browser bundle |
| 8. Webhooks and jobs | Idempotent handlers, retries and scheduled work |
| 9. Free tier honesty sheet | Read limits before you build on them |
| 10. Watch the live system | Errors, slow queries and alert-to-fix loops with a human gate |
| 11. Rules block and prompts | A paragraph for CLAUDE.md, AGENTS.md or a Cursor rule, plus 14 prompts |
| 12. Sources | What we used and how we used it |