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:

  • 2,343 questions (all MCQ type), 2,265 approved / 78 draft / 8 archived
  • 15 top-level keys in the JSON (schemaVersion, appVersion, exportedAt, questions, subjects, topics, chapters, subtopics, tags, customTypes, collections, standards, tests, caseGroups, settings)
  • Questions carry 29 always-present fields plus 9 partially populated ones (chapter, subtopic, caseGroupId, nature, notes, course, source, reference, author); 79% have empty explanations
  • 15 tests with versioning; 12 case groups defined but 57 distinct caseGroupId values in use (45 dangling)
  • 0 populated journalEntries, tAccounts, schedules, given, required, commonMistakes, standard, standardParagraph — schema-only today
  • Firebase web API key committed in HTML (public-by-design identifier, not a secret; security via Firestore rules + App Check)
  • 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:

  • Long-lived pool + background jobs: Test generation, grading, and bulk imports need minutes of CPU and persistent DB connections — Workers' 30 s ceiling makes them infeasible.
  • Full crate ecosystem: argon2, oauth2, sqlx, axum, tower, tracing, chrono, serde, validator, uuid, deadpool all work without WASM shims.
  • Compile-time SQL safety: sqlx macro checks queries against a live DB (or offline .sqlx cache) — catches schema drift at build time.
  • Standard Postgres: JSONB, advisory locks, LISTEN/NOTIFY, materialized views, full-text search — all available if needed later.
  • Migration parity with ADR-002/003: The auth module (ADR-002) uses 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.
  • Operational familiarity: Team knows Fly.io/Railway + Postgres; debugging a stuck migration or connection leak is a known playbook, not a WASM mystery.
  • Consequences

    Positive

  • No artificial CPU/time limits on request handlers or background workers.
  • Mature, well-documented stack; hiring and onboarding are straightforward.
  • Neon serverless Postgres gives autoscaling storage + pgbouncer pooling; pay for what you use.
  • Cloudflare proxy absorbs DDoS, provides WAF, TLS termination, and edge caching for static assets.
  • Schema changes via sqlx migrate are versioned, reviewable in PRs, and reversible.
  • Background job queue (Redis + deadpool-redis + tokio workers, optional; sessions remain in Postgres per ADR-002) can run on the same host or a separate worker replica.
  • Negative

  • You now operate a server: OS patches, runtime updates, uptime monitoring, log aggregation.
  • Fly.io / Railway cold starts on scale-to-zero (mitigated by keeping 1 replica warm).
  • Neon connection limits: serverless pool defaults to ~100 connections; requires max_size tuning in deadpool-postgres.
  • SQLx compile-time checks need a live DB or a checked-in .sqlx cache (add to repo, update on migrations).
  • Redis adds a second infra piece (Fly.io Redis, Railway Redis, or Upstash) for job queue only; sessions live in the Postgres sessions table per ADR-002 — Redis is not on the auth path.
  • Cross-region latency: if API runs in 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)
  • Neon PostgreSQL (managed), Redis (Fly.io / Railway / Upstash, optional — job queue only), Cloudflare (Pages, DNS, WAF, proxy)
  • 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.