ADR-001: Backend host and runtime
Status: Accepted — ratified by product owner on 2026-11-21. Supersede only with a new ADR.
Date: 2026-11-21
Context
The current application is a single-file admin tool (index (3).html, 7,794 lines) with 176 state.db.* occurrences across 162 lines of the classic script. All data lives in a 4.18 MB JSON document (TestBank_Backup_2026-11-21.json, schemaVersion 1) containing 2,343 questions, mirrored to a single Firestore document (testbank/main) using revision-based compare-and-swap via runTransaction. Persistence must become server-authoritative and multi-tenant. The app currently uses Firebase anonymous auth (everyone shares one document) and has no user concept at all.
Key data characteristics driving the backend choice:
Options considered
| Option | What it buys | Cost/limits | Verdict |
|--------|--------------|-------------|---------|
| A) Axum + SQLx + PostgreSQL (Neon managed) on Fly.io / Railway, Cloudflare Pages + /api/* proxy | Long-lived connection pool, background workers for test generation/grading, full Rust crate ecosystem, no 30 s CPU ceiling, compile-time SQLx query checking, standard Postgres feature set | Operate a server (patches, uptime); Fly/Railway cold starts; Neon serverless pooling (pgbouncer-style) connection limits; SQLx offline .sqlx cache needed for CI | Chosen |
| B) Cloudflare Workers (workers-rs) + D1 | Zero-ops, global edge, pay-per-request, built-in D1 SQLite | 30 s CPU limit per request (hard ceiling for test generation/grading), no background workers, D1 write throughput limits, limited crate compatibility (no tokio/sqlx native), no long-lived connections | Rejected |
| C) Cloudflare Containers | Longer-lived containers, more CPU/memory, can run background tasks | Beta, pricing unclear, still edge-bound (no persistent disk), less mature than Fly/Railway for standard web services | Rejected |
Decision
A. Rust Axum + SQLx + PostgreSQL (Neon managed), deployed as a normal long-lived process on Fly.io or Railway. Cloudflare sits in front only for Pages hosting, DNS, WAF, and /api/* reverse proxy.
Why:
argon2, oauth2, sqlx, axum, tower, tracing, chrono, serde, validator, uuid, deadpool all work without WASM shims.sqlx macro checks queries against a live DB (or offline .sqlx cache) — catches schema drift at build time.LISTEN/NOTIFY, materialized views, full-text search — all available if needed later.argon2 and oauth2 crates that require native TLS; tenancy (ADR-003) enforces ownership with application-level predicates on Postgres (owner_id, pool_visible), which RLS could later harden. Both are trivial on Axum/Postgres, impractical on Workers.Consequences
Positive
sqlx migrate are versioned, reviewable in PRs, and reversible.deadpool-redis + tokio workers, optional; sessions remain in Postgres per ADR-002) can run on the same host or a separate worker replica.Negative
max_size tuning in deadpool-postgres..sqlx cache (add to repo, update on migrations).sessions table per ADR-002 — Redis is not on the auth path.iad and Neon in ewr, add ~2 ms per query; consider co-location.Revisit triggers
Flip to Workers + D1 if all three hold:
1. Test generation/grading can be refactored into < 30 s chunks or offloaded to a separate queue worker.
2. D1 write throughput and storage limits accommodate 2,343+ questions with full history + per-user private questions.
3. The team accepts WASM-target compilation for all crates (no tokio, no native TLS, no ring/argon2 without WASM builds).
Migration path (if revisited)
1. Provision a Cloudflare D1 database and mirror the Postgres schema (SQLite-compatible subset).
2. Rewrite SQLx queries to use sqlx::sqlite or raw libsql — most queries are standard SQL; only JSONB and advisory locks need translation.
3. Move background jobs to a separate Cloudflare Queue consumer (Workers can trigger, not run long tasks).
4. Deploy API as a Worker with workers-rs + axum adapter; proxy /api/* from Pages Functions.
5. Keep Neon as fallback during transition; dual-write for 2 weeks, then cut over.
6. Migrate auth: argon2 has a WASM build (argon2-wasm crate) but with 3× CPU cost; oauth2 crate works in WASM. Sessions move to D1 + KV.
7. Migrate tenancy: RLS policies become application-level checks in Workers middleware (no native RLS in D1).
Dependencies
Crate versions are indicative only — resolve the current stable release of each at implementation time rather than copying these pins.
axum 0.7+, sqlx 0.7+ (postgres, runtime-tokio, macros, migrate), deadpool-postgres 0.12+, tokio 1.38+argon2 0.5+, oauth2 5.0+, rand 0.8+, sha2 0.10+ (for session hashing)tower 0.4+, tower-http 0.5+ (CSRF, CORS, compression), validator 0.16+serde 1.0+ (json), chrono 0.4+, uuid 1.4+ (v7), thiserror 1.0+tracing 0.1+, tracing-subscriber 0.3+, opentelemetry 0.24+ (optional)Open questions
1. Fly.io vs Railway — decide after a 1-week trial deploy of the same Dockerfile on both.
2. Neon project region — pick closest to primary user base (likely us-east-1 or ap-southeast-1).
3. Whether to run DB migrations via sqlx migrate run in the container entrypoint or as a separate CI step.
4. Connection pool sizing: start with max_size=20 per replica; tune after load test with 100 concurrent test-generation jobs.
5. Observability stack: tracing + tracing-subscriber + OpenTelemetry → Grafana Cloud (free tier) or self-hosted Loki/Tempo?
6. Redis provider: Fly.io managed Redis vs Upstash (serverless, pay-per-request) vs Railway Redis — compare cold-start latency for job queue enqueue; Redis is optional and not on the auth path.