# [Worker Name]

An edge API on Cloudflare Workers. Hono in front, D1 for state, KV for sessions.

## Source of truth
Wrangler-driven. `wrangler deploy` from local pushes the worker. The deployed version is canonical. Preview deployments via `wrangler versions deploy` per branch.

## Tech stack
TypeScript on Cloudflare Workers runtime (V8 isolates, not Node). Hono 4 for routing (small, fast, edge-native). D1 for SQL at the edge (SQLite-compatible). KV for sessions + cache. R2 for object storage. Durable Objects only when you need strict consistency (chat rooms, counters, locks). Wrangler for dev + deploy.

## Deploy
`wrangler deploy` for production. `wrangler versions deploy` for previews. Routes assigned via `wrangler.toml` (`yourdomain.com/api/*`).

## File map
- `src/index.ts` Hono app, route mounting, env typing
- `src/routes/` route modules
- `src/middleware/` auth, CORS, request ID
- `src/db/` D1 query helpers + migrations (`migrations/0001_init.sql` etc)
- `src/durable-objects/` DO classes (if used)
- `wrangler.toml` bindings (D1, KV, R2, DOs), routes, env
- `worker-configuration.d.ts` auto-generated Env types

## .env / wrangler bindings
- `D1_DB` Cloudflare D1 database binding
- `SESSIONS` KV namespace binding for sessions
- `R2_BUCKET` (if needed)
- `JWT_SECRET` set via `wrangler secret put JWT_SECRET`
- `STRIPE_SECRET` if relevant, also via `wrangler secret put`

## Hard rules
- Runtime is V8 isolate, NOT Node. `fs`, `crypto` Node module, raw `Buffer` do not exist. Use Web APIs.
- D1 queries via prepared statements only (`.prepare().bind(...).all()`). String concat is SQL injection.
- KV reads are eventually consistent globally. Don't use KV for anything that needs read-your-writes.
- Secrets via `wrangler secret put`. Never in `wrangler.toml` (committed file).
- CPU limit on Workers: 50ms paid, 10ms free tier. Heavy work goes to a separate Worker or Queue.
- Migrations applied with `wrangler d1 migrations apply DB_NAME`.

## Recent significant changes
- 2026-05-04: Scaffolded. Locked: Hono over itty-router (more batteries), D1 over Postgres-via-fetch (latency), KV for sessions (sub-ms reads at the edge).

## Next session: start here
1. `npm create cloudflare@latest` if starting fresh, or clone this CLAUDE.md into existing project.
2. `wrangler d1 create your-db`. Update `wrangler.toml` with returned ID.
3. `wrangler d1 migrations create your-db init`. Write schema.
4. `wrangler dev` to test locally.
5. `wrangler deploy` once you have a route to deploy.