vibed/quotesdb/.nbd/tickets/af56a7.md

+++ title = "Write docs/LOCAL_DEV.md — local dev quickstart (cargo run + trunk serve, rusqlite, DATABASE_URL)" priority = 5 status = "todo" ticket_type = "task" dependencies = ["33ed29"] +++

The `quotesdb` API is built with Axum + Tokio, targeting Cloudflare Workers via `workers-rs`. It serves JSON at `/api/*` endpoints and persists data to Cloudflare D1 (production) or a local SQLite file (development).

TRIAGE 33ed29 resolved the local dev database strategy: plain rusqlite with a local SQLite file. No Turso, no wrangler, no Cloudflare account required for local development.

Selection is compile-time via cfg(target_arch = "wasm32"):

• wasm32 → workers-rs D1 bindings (production)
• native → rusqlite + tokio-rusqlite with a local .sqlite file (dev/test)

The native main() (see ticket 6e829e) reads DATABASE_URL from the environment, defaulting to ./quotesdb.sqlite, and calls repo.run_migrations() on startup to create tables if they don't exist.

Write `docs/LOCAL_DEV.md` explaining how to set up and run the quotesdb project locally:

1. Prerequisites — Rust (via Nix flake), no Cloudflare account needed
2. Running the API:
   • cargo run from the quotesdb/ directory
   • Listens on localhost:3000
   • Creates ./quotesdb.sqlite automatically on first run
   • Override DB path: DATABASE_URL=/path/to/db.sqlite cargo run
3. Running the UI:
   • trunk serve from the quotesdb/ directory
   • Listens on localhost:8080
   • Proxies /api/* to localhost:3000 (see Trunk.toml [[proxy]] block)
4. Environment variables:
   • DATABASE_URL — path to SQLite file (optional, default: ./quotesdb.sqlite)
   • No other variables required for local dev
5. Local dev workflow (two terminals):

   # Terminal 1 — API
   cargo run
   # Terminal 2 — UI
   trunk serve
   # Open http://localhost:8080
   

6. No wrangler required — cargo run uses the native Axum server with rusqlite directly. Wrangler is only needed for Workers deployment (handled by CI/infra).
7. Database notes:
   • Schema is applied automatically via run_migrations() on first cargo run
   • Delete ./quotesdb.sqlite to start fresh
   • sqlite3 ./quotesdb.sqlite for manual inspection

- TRIAGE 33ed29: rusqlite + local SQLite file (not Turso, not wrangler dev) - TRIAGE a9534d: Trunk proxy for `/api/*` (not CORS middleware) - TRIAGE e8a330: no SQLx, `cfg(target_arch)` split - Do not document `.env` files directly — list the env vars and their defaults, but note that `.env` is gitignored. - Cross-reference tickets 6e829e (api main.rs), dc3d2b (Trunk.toml), and 00aff0 (DB abstraction). - Keep it concise — it's a quickstart, not exhaustive reference docs. `docs(quotesdb): write LOCAL_DEV.md — local dev quickstart for api and ui`