Decide the post-Supabase provider set (Postgres / auth / storage / email)

[AlaskanTuna]

Supabase supplies four separate things — Postgres, Auth/SSO, Storage, and (indirectly) transactional email via a Resend SMTP relay configured inside Supabase Auth. Exiting means choosing four replacements, and the choices are coupled: the auth provider determines whether user UUIDs survive, which determines whether Project.userId needs a backfill, which determines the order of tasks 5 and 7. This is a decision task — its deliverable is a recorded decision in docs/decisions.md, not code. The recommendation below is researched but must be confirmed by the human at Gate 1, because it commits the project to a specific vendor set for the foreseeable future.

Researched recommendation, with the disqualifying facts that drove it:

Concern	Recommendation	Why, and what was ruled out
Postgres	Neon free plan	Neon's free plan has no inactivity-based pause, archival, or deletion — the only idle behaviour is compute scale-to-zero after 5 minutes, which resumes automatically on the next connection. That is precisely the failure being escaped. Limits: 0.5 GB storage/project, 100 CU-hours/month, 5 GB transfer/month; exceeding any of these suspends compute until the next monthly window (data is never deleted). Render Postgres is disqualified — free databases expire 30 days after creation and are deleted after a 14-day grace period. Aiven pauses inactive databases. Xata's managed free database is removed after a set period.
Storage	Cloudflare R2	10 GB storage, 1M Class A + 10M Class B operations/month, $0 egress, permanently free, no idle expiry. S3-compatible, so the swap is an @aws-sdk/client-s3 drop-in behind the three functions in storageService.ts. Preserves the one-Solar-API-call-per-location cache constraint exactly.
Auth	Better Auth, self-hosted in the Express backend, tables in the same Neon database via the Prisma adapter	The decisive property is user-ID preservation: Better Auth's user table takes a String id, so the rescued Supabase UUIDs can be inserted verbatim and every Project.userId FK survives with zero backfill. It supports email+password with requireEmailVerification, Google OAuth via socialProviders, and a user-supplied sendVerificationEmail callback that wires straight to Resend. No MAU cap, no vendor that can change its free tier, no idle pause. Alternative worth considering: Clerk (free to 50k MRU as of Feb 2026, far less engineering) — but Clerk mints its own user_... ids, forcing either a mapping table or a Project.userId migration, and re-introduces exactly the "someone else's free tier" dependency this phase exists to remove.
Email	Resend, called directly from the backend	Already the underlying sender; today it is merely relayed through Supabase Auth's SMTP config. solarsim.tech is already verified in Resend with DKIM, SPF, and an MX bounce route (per RUNBOOK.md), and RESEND_API_KEY is already in .env.example. Removing the Supabase relay is therefore a simplification, not a new integration — no DNS work.

Scope: docs/decisions.md, docs/trd.md

Checklist

• Re-verify each provider's current free-tier terms at decision time rather than trusting this table — free-tier terms move fast and this plan was written 2026-07-29
• Confirm the Neon free-plan headroom against real numbers from the task 1 rescue: total public schema size must fit 0.5 GB (GeoTIFFs live in object storage, not Postgres, so this should be comfortable — confirm, don't assume)
• Compute the CU-hour budget: Neon free is 100 CU-hours/month and free-plan compute floors at 0.25 CU, giving roughly 400 hours of active compute. Record the consequence explicitly: a keep-alive pinger that touches the database will hold compute awake ~730 h/month ≈ 180 CU-hours and suspend the project. This constrains task 10's cold-start mitigation.
• Confirm the total rescued storage-object footprint fits R2's 10 GB free tier
• Spike Better Auth for one hour against a throwaway Neon database: insert a user row with a hand-chosen UUID, sign in with email+password, and confirm the id round-trips into the session — this is the single assumption the whole auth plan rests on
• Decide and record: if the spike fails, fall back to Clerk and accept a Project.userId backfill migration as an added task
• Append one line per settled choice to docs/decisions.md (four lines: Postgres, storage, auth, email)
• Update the infrastructure section of docs/trd.md to name the new providers — docs/trd.md is canonical for architecture and must not be left describing Supabase
• verify: docs/decisions.md contains four dated one-line entries, each with a rationale clause
• verify: the Better Auth spike's custom-UUID result is pasted into the GitHub issue as evidence, not asserted

---

_{Priority: Critical · Phase 12 task 4 of the maintainer's migration plan.}

[AlaskanTuna]

Provider set settled

Concern	Decision	Status
Postgres	Neon	Shipped and proven (PR #22)
Object storage	Cloudflare R2	Shipped and proven (PR #22)
Auth	Better Auth, self-hosted	Decided — issue #6
Email	Resend, called directly	Decided — issue #7

Postgres and storage are no longer recommendations: both carry real production data and were verified live, including an 11-minute Neon scale-to-zero resume (HTTP_200 in 2.17s) and a real panel recompute against R2-hosted GeoTIFFs with zero calls to solar.googleapis.com.

Auth decision rationale changed mid-flight

The maintainer authorised discarding all 16 UAT user records — only cached Location rows and R2 GeoTIFFs are considered irreplaceable. That removes user-ID preservation, which was the original decisive criterion for Better Auth over Clerk.

Verified this is structurally safe before accepting it:

• Location has no user column at all
• Project.userId has no FK constraint (which is why 2 orphans already exist)
• 4 of 19 Locations already have no Project referencing them
• Deleting users cascades only to profiles and auth.*

Better Auth still wins, on the reason this phase exists: Clerk would re-introduce a third-party free tier that can pause or change terms — the exact failure being escaped. Deletion itself is deferred to #8, which drops the auth schema wholesale.

Better Auth spike — evidence

Real install of better-auth@1.6.25 + @better-auth/prisma-adapter@1.6.25 against Prisma 6.

Generates 4 tables: user, session, account, verification. User.id is String @id with no DB default (app-generated base62, overridable via advanced.database.generateId) — so arbitrary UUIDs would have been assignable had preservation still mattered. Password hashes live in Account.password, not on User. Prisma adapter peer range is ^5 || ^6 || ^7, so no Prisma upgrade is forced.

Honest limitation: live end-to-end sign-in was not proven. The disposable Neon branch's credential went stale mid-spike due to a rotation on my side — a setup error, not a library problem. Schema generation, Prisma client generation, tsc, and the Express handler mount (GET /api/auth/ok → 200) all succeeded. Recording this as unproven rather than claiming a pass.

Integration facts that shape #6:

• Express 5 needs app.all('/api/auth/*splat', toNodeHandler(auth)), and it must precede express.json()
• Google redirect URI to register: <baseURL>/api/auth/callback/google
• Email verification is not on by default — needs requireEmailVerification: true to match today's enable_confirmations
• Origin validation is enforced (non-browser callers need an explicit Origin header)
• Google OAuth tokens land in Account unencrypted by default — evaluate account.encryptOAuthTokens: true
• The { id, email } seam is auth.api.getSession({ headers: fromNodeHeaders(req.headers) }), matching the existing requireAuth contract exactly

Neon free-tier constraint with a downstream consequence

100 CU-hours/month against a 0.25 CU floor ≈ 400 hours of active compute. A keep-alive pinger would hold compute awake ~730 h/month ≈ 180 CU-hours and suspend the project. Issue #9's cold-start mitigation therefore cannot be a database pinger.

[AlaskanTuna]

All four provider decisions are settled and recorded in the decision log; TRD provider sections updated. Postgres and storage are shipped and proven (#4, #5). Auth and email decisions carry into #6 and #7. The full Supabase reference sweep across the TRD/README remains #8.