Decisions - living ledger

Maintained by Claude. One line at a time. Nothing is Confirmed without your explicit yes. Updated 2026-05-30.

Confirmed

• New clean repo; migrate verified files one at a time from outside-in.
• Active first wave = the three public landing pages already started in E:\blockdata.
• Auth-gated pages move one page/workflow at a time.
• For each auth-gated page, bring only the backend pieces that page actually needs: auth/session handling, API endpoints, models, DB tables/migrations, secrets/env, storage, or service adapters.
• The migration unit is page/workflow -> required frontend components -> required API/backend contract -> required data/secrets/deploy config -> live verification.
• Minted asset_id, no source_uid.
• Drop the Supabase platform: Auth, Storage, Realtime, and Edge Functions do not move as platform dependencies.
• Auth = Better Auth (self-hosted) on Cloudflare Workers + Neon — the Supabase-Auth replacement. It issues sessions/JWT; the FastAPI backend validates them. (Cloudflare Access gates internal resources like the docs — that is not product auth.)
• Postgres = Neon, designed cleanly as each page slice needs data.
• Existing SQL/migration files here are reference material only; do not copy old migration history into the new repo.
• Cloudflare hosts dev + prod.
• Object storage = R2.
• Keep Python / FastAPI where backend slices require Python runtime behavior such as Pydantic AI, SQLAlchemy, or SQLAdmin.
• Editor = Tiptap.
• Dev loop: local IDE -> push to GitHub -> push updates site, APIs, and DB migrations. The site auto-deploys; migrations run as a CI step.

Target Workflow

local IDE -> git push -> CI / Cloudflare build -> site + APIs + DB update

• Frontend site: Cloudflare Pages, connected to GitHub, with production URL and per-branch preview URLs.
• APIs: Workers and/or Containers redeploy on push as each page slice requires them.
• DB migrations: GitHub Actions applies the new Neon migration chain. Neon can branch a DB per PR; merge to main migrates production. Migrations stay separate from the app deploy.
• Page-slice rule: if a page requires API work, stand up that API slice in the new dev environment for that page before moving the next page.
• Data rule: one page may create one table, or a small group of tables if that workflow truly requires them. Do not pre-port the old database.

Open

• Database implementation details: migration runner, branch naming, and dev/prod connection wiring for Neon.
• Python host: Cloudflare Containers require Workers Paid plan.
• Per-worker backends: local if private to this machine; Cloudflare-hosted if shared or internet-facing.
• Vercel: recommended out; Cloudflare Pages covers the site. Pending explicit confirmation.
• Cache/queues, frontend framework details, monorepo tooling, and final repo naming.

Facts

• CF account token has previously been verified for provisioning R2, Workers, Pages, D1, KV, Queues, Vectorize, Hyperdrive, and Durable Objects in this greenfield direction.
• Containers are blocked until the Workers Paid plan is available.
• Postgres is external managed Neon. Cloudflare Workers can reach Postgres through Hyperdrive; Python containers use the provider connection or pooler DSN through SQLAlchemy unless proven otherwise.
• Owned zones include blockdata.run, datablocks.run, dbase.run, kaiai.dev, and legal-10.us.

Credentials & access (workers: read this before asking Jon to log in)

All infra + auth credentials live in SOPS (secrets/dev/*.yaml), indexed in WORKER-ACCESS.md (gitignored, machine-local). Use sops exec-env <file> "<cmd>". Never ask Jon to log in, re-auth, or "set up" anything already provisioned here — only a genuinely new owner-only grant (new account / billing / OAuth app) gets a one-time, concise ask.

• Cloudflare (Pages, R2, Workers, DNS, Access): secrets/dev/cloudflare.yaml → CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.
• Neon (Postgres): secrets/dev/neon.yaml → NEON_API_KEY, NEON_PROJECT_ID, NEON_PROD_DATABASE_URL, NEON_DEV_DATABASE_URL.
• Better Auth (login slice): secrets — BETTER_AUTH_SECRET, OAuth client id/secret — go into SOPS secrets/dev/auth.yaml and the Worker env; record them in WORKER-ACCESS.md when created.
• GitHub: gh CLI authed as prophetto1 (incl. workflow scope). CI uses repo secrets CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID.
• Docs gate: docs.blockdata.run sits behind Cloudflare Access (team emails) — resource gating, not product login.

Change a line by saying confirm <topic> = <choice> or reopen <id>.