Prerequisites & Decision Register

Core Principles

These principles govern every decision in this document. When two options are equally viable, apply the principle that eliminates the most future regret.

What This Document Covers

This document sits before the technical architecture. The architecture describes how the system is built. This document captures what must be decided, acquired, and confirmed before building begins. It answers:

• Which services are truly necessary at MVP versus which ones feel necessary?
• Which technology decisions are high-stakes (hard to undo) versus low-stakes (swap in a day)?
• What accounts and tools must exist on day one?
• What does "launch" actually cost per month?
• What decisions are intentionally deferred, and what triggers revisiting them?

1 Minimum Viable Infrastructure

There is a meaningful distinction between what is needed to ship and what is needed to scale. The table below makes that explicit with two tiers.

Service Audit — Questioning Every Dependency

Each of the following is commonly assumed to be necessary at MVP. The audit asks whether that assumption holds for Groundwork at the actual launch scale.

2 Decision Register

Each decision below covers the realistic option set, the key differentiating question, trade-offs, and a recommendation. High-stakes decisions (those with high exit costs) are flagged clearly.

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck
      - run: pnpm lint
      - run: pnpm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: fly deploy --remote-only  # ← swap this line to change providers

3 Portability Assessment

Every vendor included in this architecture must speak a documented standard protocol and have a migration path that takes under one day. This table is the accountability record for that claim.

4 Accounts & CLI Tools Needed

This is a literal checklist. Complete it before writing code. Items are ordered by dependency — some tools are required before others can be configured.

Accounts (create in this order)

• GitHub

  github.com — source control, pull request workflow, GitHub Actions CI/CD. Free for private repos. Create the groundwork repository here first.
• Fly.io

  fly.io — container hosting and managed Postgres. Free tier includes 3 shared VMs and 3 GB Postgres storage. Add a credit card to the account (required to deploy beyond the free tier limits, but not charged until limits are exceeded).
• Resend

  resend.com — transactional email. Free tier: 3,000 emails/month. Verify your domain DNS records during account setup (add the required TXT and MX records to Cloudflare).
• Sentry

  sentry.io — error tracking. Free tier: 5,000 errors/month. Create a new project, select SvelteKit as the platform. Copy the DSN — it goes in PUBLIC_SENTRY_DSN environment variable.
• Cloudflare

  cloudflare.com — DNS management. Free. Add your domain here and point the nameservers from your registrar to Cloudflare. This also unlocks free DDoS mitigation and basic CDN.
• UptimeRobot

  uptimerobot.com — uptime monitoring. Free: 50 monitors, 5-min intervals, email alerts. Set up after first deploy. Not blocking.

Local CLI Tools

• Docker Desktop

  docker.com — local development environment and deployment artifact. Required.
  brew install --cask docker
• Node.js 20 LTS

  nodejs.org — runtime. Use the LTS version. Install via nvm or fnm to support future version switching.
  brew install fnm && fnm install 20
• pnpm

  Package manager. Faster installs, strict dependency resolution, workspace support for potential monorepo expansion.
  npm install -g pnpm
• Fly CLI (flyctl)

  Required for Fly.io deploys, Postgres management, secrets, and SSH access to VMs.
  brew install flyctl
• psql (Postgres CLI)

  For direct database inspection, migrations, and debugging. Installed with Postgres client libraries.
  brew install libpq && brew link --force libpq
• GitHub CLI (gh)

  For managing PRs, secrets, and Actions workflows from the terminal. Optional but recommended.
  brew install gh && gh auth login

Not Needed at MVP

These are commonly acquired prematurely. Do not create these accounts until the documented trigger is reached.

Bootstrap: First Day Commands

# 1. Authenticate with providers
gh auth login
flyctl auth login

# 2. Create the SvelteKit project
pnpm create svelte@latest groundwork
cd groundwork
pnpm install

# 3. Initialize local Postgres via Docker (dev only)
docker compose up -d  # expects docker-compose.yml in repo root

# 4. Create Fly.io application and managed Postgres
flyctl launch --no-deploy
flyctl postgres create --name groundwork-db

# 5. Set secrets (do not commit these to .env in production)
flyctl secrets set DATABASE_URL="postgres://..."
flyctl secrets set BETTER_AUTH_SECRET="$(openssl rand -base64 32)"
flyctl secrets set RESEND_API_KEY="re_..."
flyctl secrets set PUBLIC_SENTRY_DSN="https://..."

# 6. First deploy
flyctl deploy

services:
  db:
    image: postgres:16-alpine
    ports: ["5432:5432"]
    environment:
      POSTGRES_DB: groundwork
      POSTGRES_USER: app
      POSTGRES_PASSWORD: dev
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

5 Dependency Budget

The maximum is 5 external services at MVP. Count them. Anything beyond this limit requires removing an existing service or deferring the addition.

6 Cost Projection

Real free tier limits are shown. Many providers give enough to launch a product with paying customers before incurring any cost.

7 Open Questions & Deferred Decisions

These decisions are intentionally not made today. Each has a documented trigger — a metric or event that signals when it's time to revisit. Tracking them here prevents both premature optimization and forgotten technical debt.

• Trigger: >1K docs
  When to add dedicated object storage

  At >1,000 documents or >1 GB total stored in Postgres, the maintenance burden of bytea storage begins to outweigh simplicity. Add R2 or Tigris at that point. Decision is pre-made: S3-compatible, zero egress, 4 environment variables to swap.
• Trigger: >50K sessions
  When to add Redis / Upstash

  At >50,000 concurrent sessions, or when a specific hot-path is identified via profiling that Postgres cannot serve acceptably, Redis becomes justified. Not before. The trigger must be measured, not assumed. BullMQ would be the queue beneficiary; session caching would be the other.
• Trigger: Team > 3
  When to migrate to Neon for database branching

  At 1–2 developers, Fly Postgres with manual branching is manageable. At 3+ developers, conflicting migrations and shared dev databases become friction. Neon's branch-per-PR model eliminates this. The migration is a pg_dump | pg_restore — not a rewrite.
• Trigger: Product decision
  Whether to support native mobile apps

  SvelteKit does not build native iOS/Android apps. If a native mobile experience becomes a product requirement (as opposed to a progressive web app), the API layer remains intact but a separate React Native or Flutter project would be needed. This decision affects hiring and app store compliance timelines. Flag early if the product direction shifts toward mobile-first.
• Trigger: Global users
  When to add a CDN beyond the hosting provider

  Cloudflare DNS and the hosting provider handle static asset delivery for US-based users adequately. When users in Europe or Asia begin representing >20% of traffic and latency complaints emerge, evaluate Fly.io's multi-region deployment (included in Fly pricing) before adding a separate CDN vendor.
• Trigger: SLA commitments
  When to add formal observability (Datadog, Grafana)

  Structured logs + Sentry + UptimeRobot is sufficient until the team is making SLA commitments to paying enterprise customers. At that point, a proper metrics pipeline (Prometheus + Grafana or Datadog) becomes justified. The cost (~$30–70/mo) is reasonable when paired with an annual enterprise contract.
• Trigger: Permit API complexity
  Which permit data APIs to integrate, and how

  Permit data availability varies significantly by jurisdiction. Some municipalities have public REST APIs; most do not. The polling strategy (Graphile Worker cron jobs hitting public permit portals) may need to evolve into web scraping with Playwright or a third-party permit data aggregator. This is a product-side open question more than a technical one — document specific target jurisdictions before building the permit polling service.