Internal Engineering Reference

Prerequisites & Decision Register

Infrastructure decisions, vendor tradeoffs, portability assessments, and cost projections for the MotoPartPicker launch stack.

Last updated April 2025
Status Decisions Finalized
Phase Pre-launch

Minimum Viable Infrastructure

What you need to ship vs. what you should have by launch day.

Bare Minimum — Can Ship Today
5 components, $0/mo
Fly.io Neon Postgres BetterAuth SvelteKit GitHub Actions
Recommended — By Launch
+ 4 additions, still ~$0/mo
+ Sentry + Resend + R2 + UptimeRobot
Capability Why It Matters Bare Minimum Recommended Can Wait
Container Hosting Run the SvelteKit app + API Fly.io free Fly.io $5/mo —
SQL Database Parts catalog, user data, compat matrix Neon free Neon Pro $19/mo —
Authentication User accounts, OAuth, sessions BetterAuth (free) BetterAuth (free) —
Object Storage User-uploaded install photos Not needed at day 0 R2 (when photos ship) Skip for MVP
Transactional Email Verification, notifications Not needed at day 0 Resend ($0 free tier) Delay if no auth email
Background Jobs Async tasks: scraping, indexing Postgres SKIP LOCKED pg-boss Redis never needed
Error Tracking Know when things break in prod Console logs Sentry (free tier) —
DNS + SSL Custom domain, HTTPS Fly.io (included) Fly.io (included) —
Uptime Monitoring Alert on outages before users do Not blocking UptimeRobot (free) —
CI/CD Automated test + deploy pipeline GitHub Actions GitHub Actions —

Decision Register

8 architectural decisions — alternatives considered, tradeoffs, and lock-in risk for each.

A

Hosting Platform

Where the containerized SvelteKit app runs

Fly.io

Options Evaluated

  • Fly.io Selected
  • Railway
  • Render
  • Google Cloud Run

Why Fly.io Wins

  • + Docker-first — no platform lock-in on runtime
  • + Edge deployment across 30+ regions
  • + Generous free tier: 3 shared VMs, included DNS/SSL
  • – CLI-first UX has a learning curve vs Railway
  • ~ Same Docker image can move to Render or Cloud Run
Lock-in Risk
Low — standard Docker image escapes in a day
B

Database

Primary data store for parts, bikes, compatibility, users

Neon Postgres

Options Evaluated

  • Neon (serverless Postgres) Selected
  • Supabase Postgres
  • Fly Postgres
  • Railway Postgres

Why Neon Wins

  • + DB branching = each PR gets its own Postgres branch
  • + Serverless scaling — zero cost at idle
  • + Free tier: 0.5GB, 190 compute hours/mo
  • – Cold start latency (~100ms) on free tier
  • ~ Standard Postgres wire protocol — pg_dump migrates anywhere
Lock-in Risk
Low — standard Postgres, pg_dump to any host
C

Authentication

User accounts, OAuth (Google/GitHub), session management

BetterAuth

Options Evaluated

  • BetterAuth Selected
  • Lucia Auth
  • Auth.js (NextAuth)
  • Clerk

Why BetterAuth Wins

  • + Library-based, self-hosted — no vendor dependency
  • + Full-featured: email/password, OAuth, magic links, 2FA
  • + Data stays in your own Postgres — no external auth DB
  • – More setup than Clerk; no hosted dashboard
  • ~ Lucia is a good alternative; BetterAuth has more batteries
Lock-in Risk
None — self-hosted library, data in your DB
D

Frontend Framework

SSR framework powering the rider-facing app — SEO is critical

SvelteKit

Options Evaluated

  • SvelteKit Selected
  • Next.js (React)
  • Remix

Why SvelteKit Wins

  • + SSR first-class — critical for "[bike] [part] compatible" SEO
  • + Smallest bundle: no virtual DOM overhead
  • + Excellent DX — less boilerplate than Next.js
  • + Built-in form actions and data loading
  • – Smaller ecosystem than React; fewer component libraries
  • ~ SEO longtail search is the primary acquisition channel here
Lock-in Risk
Medium — Svelte syntax, but API layer is portable
E

Object Storage

User-uploaded install photos, part images, static assets

Cloudflare R2

Options Evaluated

  • Cloudflare R2 Selected
  • AWS S3
  • Tigris (Fly-native)

Why R2 Wins

  • + Zero egress fees — huge at scale for an image-heavy product
  • + S3-compatible API — existing tooling works unchanged
  • + Free: 10GB storage, 10M Class A reads/mo
  • – Cloudflare account required; not needed until photo uploads ship
  • ~ S3-compatible means rclone sync migrates to any provider
Lock-in Risk
Low — S3-compatible, migrate with rclone
F

Transactional Email

Verification, password reset, notifications to riders

Resend

Options Evaluated

  • Resend Selected
  • SendGrid
  • Postmark

Why Resend Wins

  • + Best-in-class DX: React Email components, typed SDK
  • + Free tier: 100 emails/day, 3,000/month
  • + Modern REST API — simple to integrate with BetterAuth
  • – Newer service; less track record than Postmark at high volume
  • ~ Same-day switch to SendGrid or Postmark via SMTP fallback
Lock-in Risk
Low — REST API with SMTP fallback available
G

Background Jobs

Async tasks: affiliate data sync, compatibility indexing, notifications

Postgres-Based

Options Evaluated

  • Postgres SKIP LOCKED → pg-boss Selected
  • BullMQ + Redis
  • Graphile Worker

Why Postgres-Based Wins

  • + No additional service — Postgres handles the queue
  • + Transactional job enqueue — no lost jobs on crash
  • + SKIP LOCKED is production-grade at this scale
  • – Not appropriate for sub-second job latency requirements
  • ~ "Can Postgres do this? Yes." — add Redis only when proven necessary
Lock-in Risk
None — standard Postgres feature
H

Monitoring & Error Tracking

Know when production breaks before riders report it

Sentry + UptimeRobot

Options Evaluated

  • Sentry + UptimeRobot Selected
  • Datadog
  • Custom logging (Axiom / Loki)
  • Bugsnag

Why Sentry + UptimeRobot Win

  • + Sentry free tier: 5K errors/mo — more than enough at launch
  • + UptimeRobot: free uptime checks every 5 minutes
  • + Sentry is open-source — self-hostable if cost becomes an issue
  • – No APM / distributed tracing at this tier
  • ~ Datadog is the upgrade path at serious scale; not justified at $0
Lock-in Risk
Low — Sentry is open-source, self-hostable

Portability Assessment

How easily can we leave each vendor if we need to?

Design principle: every service in this stack was chosen to be replaceable. Standard protocols and open-source tooling are non-negotiable constraints, not aspirations.
Vendor What For Standard Protocol Migration Path Effort
Fly.io Container hosting Docker image Same image → Railway, Render, or Cloud Run 1 day
Neon Primary database Postgres wire protocol pg_dump → any managed Postgres host 2–4 hours
BetterAuth Authentication Library (no vendor) Data is in your Postgres; swap library or self-implement 1–3 days
Cloudflare R2 File storage S3-compatible API rclone sync r2: s3: — any S3-compatible store Half day
Resend Transactional email REST API + SMTP fallback Switch to SendGrid or Postmark same day via SMTP Same day
Sentry Error tracking Open-source (self-hostable) Self-host on Fly.io or switch SDK to Bugsnag 1–2 days
Stripe Retailer billing Proprietary API Customer export possible; rebuilding Billing Portal is 2–4 weeks 2–4 weeks

Accounts & CLI Tools Needed

Everything you need to set up before writing the first line of app code.

Accounts to Create

  • GitHub — source of truth for code + CI/CD
  • Fly.io — container hosting + DNS/SSL
  • Neon — serverless Postgres database
  • Cloudflare — R2 object storage (when photos ship)
  • Resend — transactional email
  • Sentry — error tracking dashboard
  • Stripe — retailer subscription billing
  • RevZilla Affiliate — parts affiliate revenue
  • Amazon Associates — parts affiliate revenue
  • Google OAuth credentials — social login via BetterAuth

CLI Tools to Install

  • Node.js 20+ — runtime for SvelteKit dev
  • pnpm — package manager (preferred over npm)
  • Docker — container build + local Postgres
  • flyctl — Fly.io deploy + secrets management
  • Neon CLI — branch management for dev environments
  • git — version control (obviously)

Local Development Setup

Use Docker Compose to run a Neon-compatible Postgres instance locally (standard Postgres image is fine — Neon branching only matters for CI/staging). Commit an .env.example file documenting every required environment variable with placeholder values. Never commit a populated .env.

Dependency Budget

Complexity compounds. Every new service costs time, money, and incident surface area.

MVP Stack
5
external services
Fly.io Neon GitHub Resend Sentry
Growth Stack
7
external services
+ R2 + UptimeRobot
Hard Limit
∞?
No. Stop here.
Justify first
Hard limit rule: No new external service may be added without answering the question "What does the existing stack definitively cannot do here?" — not "it would be nicer" or "the docs look cleaner." Document the answer in this register before merging.

Cost Projection

Free to launch. First real bill appears around Month 3–4 when you get traction.

$0
At Launch
Day 0 — all free tiers
~$70
First Paid Month
Month 3–4, with real traffic
$5–50
Scaling Range
As Fly.io + Neon scale
Service Free Tier When You Pay First Paid Tier
Fly.io 3 shared VMs, included DNS/SSL >256MB RAM or persistent volume $5/mo
Neon Postgres 0.5GB storage, 190 compute hours/mo >0.5GB or more compute / branching $19/mo
Cloudflare R2 10GB storage, 10M Class A reads/mo >10GB stored $0.015/GB
Resend 100 emails/day (~3,000/mo) >3,000 emails/month $20/mo
Sentry 5,000 errors/month >5,000 errors/month $26/mo
GitHub Actions 2,000 minutes/mo (public repos: unlimited) >2,000 minutes on private repo $0 (public repo)
UptimeRobot 50 monitors, 5-minute checks Never, at this scale $0 (free forever)
TOTAL — MVP Launch $0/mo ~Month 3–4 with real traffic ~$70/mo