Infrastructure Plan

1. Infrastructure Overview

Groundwork runs on four independent control planes: Netlify for the frontend, Fly.io for the API and background workers, Neon for the database, and Cloudflare R2 for file storage. This decomposition keeps each layer independently scalable and avoids any single-vendor lock-in on the critical path.

2. Hosting Architecture

2.1 Netlify — Frontend

The SvelteKit application is deployed to Netlify using @sveltejs/adapter-netlify. Static assets (JS bundles, CSS, fonts, images) are served from Netlify's global CDN. Server-side rendering runs inside Netlify Functions (AWS Lambda under the hood, 1 vCPU, 1024MB, 10s timeout).

[build]
  command   = "npm run build"
  publish   = ".svelte-kit/netlify/static"

[build.environment]
  NODE_VERSION = "20"

# SSR Function handler
[[functions]]
  directory = ".svelte-kit/netlify/functions"

# Cache static assets aggressively
[[headers]]
  for = "/_app/immutable/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

# Security headers on all routes
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options        = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy        = "strict-origin-when-cross-origin"
    Permissions-Policy     = "camera=(), microphone=(), geolocation=()"
    Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"

# SPA fallback for client-side navigation
[[redirects]]
  from   = "/api/*"
  to     = "https://api.groundwork.app/:splat"
  status = 200
  force  = true

2.2 Fly.io — API Service

The API is a Node.js (Fastify) application running on Fly.io. Node.js is recommended over Go here because the team can share code and types between the SvelteKit frontend and the API (e.g., Zod schemas, shared utility functions), reducing duplication and accelerating the early build. Go would be appropriate if the API needs to handle sustained CPU-bound work at high concurrency — that's not the Launch or Growth profile.

app      = "groundwork-api"
primary_region = "iad"

[build]
  dockerfile = "Dockerfile"

[env]
  PORT        = "8080"
  NODE_ENV    = "production"
  LOG_LEVEL   = "info"

[[services]]
  protocol   = "tcp"
  internal_port = 8080

  [services.concurrency]
    type       = "requests"
    hard_limit = 200
    soft_limit = 150

  [[services.ports]]
    port     = 443
    handlers = ["tls", "http"]

  [services.http_checks]
    interval      = "15s"
    timeout       = "5s"
    grace_period  = "10s"
    method        = "GET"
    path          = "/health"
    protocol      = "http"

# Auto-scale: min 1, max 4 machines
[http_service]
  auto_stop_machines  = false  # keep ≥1 warm
  auto_start_machines = true
  min_machines_running= 1

[[vm]]
  cpu_kind = "shared"
  cpus     = 1
  memory_mb= 512

2.3 Fly.io — Background Workers

Workers are a separate Fly.io app (groundwork-workers) so they can scale independently of the API and be deployed or restarted without impacting live traffic. They pull from an in-process queue backed by Neon (using the pg-boss library) and scale to zero between bursts.

app            = "groundwork-workers"
primary_region = "iad"

[build]
  dockerfile = "Dockerfile.worker"

# No public service — workers are internal only
# They communicate outbound only (Resend, Neon, R2)

[[vm]]
  cpu_kind  = "shared"
  cpus      = 1
  memory_mb = 512

# Scale to zero; woken by pg-boss polling
[http_service]
  auto_stop_machines  = true
  auto_start_machines = true
  min_machines_running= 0

2.4 Region Strategy

3. Database Setup

3.1 Neon Project Configuration

One Neon project holds all environments as separate branches. The project lives in us-east-1 (AWS), co-located with Fly.io iad to minimize network round-trips.

# Install Neon CLI
npm install -g neonctl
neonctl auth

# Create project (do this once)
neonctl projects create \
  --name groundwork \
  --region-id aws-us-east-1 \
  --pg-version 16

# List branch connection strings
neonctl connection-string --branch main
neonctl connection-string --branch staging

# Create staging branch from main
neonctl branches create --name staging --parent main

# Create a per-PR branch (run in CI)
neonctl branches create \
  --name "preview/pr-$PR_NUMBER" \
  --parent staging

3.2 Connection Pooling

Every application connects through Neon's built-in pgbouncer endpoint (port 5432, transaction pooling mode). Direct connections (port 5432 on the non-pooler hostname) are used only for migrations, which require session mode.

# Runtime connection (pooled — use this in app code)
DATABASE_URL=postgres://user:pass@ep-xxx-pooler.us-east-1.aws.neon.tech/neondb?sslmode=require

# Migration connection (direct — use only in migration scripts)
DATABASE_URL_DIRECT=postgres://user:pass@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require

# SSL is enforced; never disable sslmode

3.3 Backup & Point-in-Time Recovery

Neon's Pro plan includes continuous WAL archiving with a 7-day PITR window. No additional backup tooling is required for the Launch or Growth phases.

# Create a restore branch from a specific timestamp
neonctl branches create \
  --name restore-2026-04-01 \
  --parent main \
  --timestamp "2026-04-01T12:00:00Z"

# Verify data in restore branch, then promote to main if correct
neonctl branches set-as-default restore-2026-04-01

3.4 Monitoring

4. CI/CD Pipeline

All code flows through GitHub. Netlify auto-deploys are the primary mechanism for the frontend. Fly.io deployments are driven by GitHub Actions to ensure migrations run before the new application code starts serving traffic.

name: Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
  NEON_API_KEY:  ${{ secrets.NEON_API_KEY }}
  NEON_PROJECT_ID: ${{ secrets.NEON_PROJECT_ID }}

jobs:
  # ── 1. Lint & Test ─────────────────────────────────────
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm run lint
      - run: npm run check     # svelte-check + tsc
      - run: npm run test:unit

  # ── 2. PR Preview (branch deploys only) ────────────────
  preview:
    if: github.event_name == 'pull_request'
    needs: [test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Create a Neon branch for this PR
      - name: Create Neon preview branch
        uses: neondatabase/create-branch-action@v5
        id: neon-branch
        with:
          project_id: ${{ env.NEON_PROJECT_ID }}
          api_key:    ${{ env.NEON_API_KEY }}
          branch_name: preview/pr-${{ github.event.number }}
          parent:     staging

      # Run migrations against the preview branch
      - name: Run migrations
        run: npm run migrate
        env:
          DATABASE_URL_DIRECT: ${{ steps.neon-branch.outputs.db_url }}

      # Netlify handles the actual preview deploy automatically
      # We just need to inject the Neon branch URL as an env var
      - name: Comment preview URL on PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Preview DB branch: \`preview/pr-${context.issue.number}\``
            })

  # ── 3. Production Deploy (main branch only) ────────────
  deploy:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: [test]
    runs-on: ubuntu-latest
    environment: production    # GitHub environment with approval gate
    steps:
      - uses: actions/checkout@v4

      # Run migrations BEFORE deploying new code
      - name: Run production migrations
        run: npm run migrate
        env:
          DATABASE_URL_DIRECT: ${{ secrets.DATABASE_URL_DIRECT_PROD }}

      # Deploy API to Fly.io
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - name: Deploy API
        run: flyctl deploy --app groundwork-api --strategy rolling

      # Deploy workers
      - name: Deploy Workers
        run: flyctl deploy --app groundwork-workers --strategy immediate

      # Netlify deploys automatically on push to main via Git integration
      # No step needed here unless you want to block on Netlify completion

4.1 Rollback Procedures

5. Environment Management

5.1 Secrets Management

# Set secrets (never committed to git)
flyctl secrets set \
  DATABASE_URL="postgres://..." \
  RESEND_API_KEY="re_..." \
  R2_ACCESS_KEY_ID="..." \
  R2_SECRET_ACCESS_KEY="..." \
  SESSION_SECRET="$(openssl rand -hex 32)" \
  --app groundwork-api

# Verify (values are redacted in output)
flyctl secrets list --app groundwork-api

6. Monitoring & Observability

6.1 Metrics

Fly.io provides built-in machine metrics (CPU, memory, network) visible in the dashboard at fly.io/apps/groundwork-api/metrics. No additional agent is required for infrastructure metrics at the Launch phase.

6.2 Error Tracking — Sentry

Sentry is installed in both the SvelteKit frontend (@sentry/sveltekit) and the Fastify API (@sentry/node). They share one Sentry project, differentiated by environment tags.

// src/hooks.server.ts
import * as Sentry from '@sentry/sveltekit';

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,
  tracesSampleRate: 0.1,      // 10% trace sampling
  profilesSampleRate: 0.05,    // 5% profiling
  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,         // PII protection
      blockAllMedia: false,
    }),
  ],
  replaysSessionSampleRate:  0.01,
  replaysOnErrorSampleRate: 1.0,
});

6.3 UptimeRobot — Synthetic Checks

Five monitors cover the critical user journeys. Alert contacts: email + Slack webhook. Check interval: 5 minutes on the free plan.

6.4 Structured Logging

The API and Workers emit structured JSON logs (via pino) to stdout. Fly.io captures these and forwards them to a log drain. At Growth phase, configure Fly.io's Grafana Cloud log drain for retention and search.

# Add Grafana Cloud log drain (Growth phase)
flyctl logs drain create \
  --app groundwork-api \
  --type http \
  --url "https://logs-prod-us-central1.grafana.net/loki/api/v1/push" \
  --header "Authorization: Basic <grafana-token>"

# Sample structured log output (pino)
{"level":"info","time":1712073600000,"reqId":"abc-123",
 "method":"POST","url":"/api/projects","statusCode":201,
 "responseTime":42,"userId":"usr_xyz","projectId":"prj_456"}

6.5 Alert Rules

7. Cost Projections

All prices are based on publicly listed rates as of Q1 2026. "Launch" assumes 50 projects and ~100 users. "Growth" assumes 500 projects and ~1,500 users. "Scale" assumes 5,000 projects and ~15,000 users.

7.1 Fly.io Machine Cost Breakdown

8. Security Infrastructure

8.1 TLS / Transport Security

8.2 Network Security

Fly.io's 6PN (private networking) is used for API-to-Worker communication. Workers never expose a public port. Neon's IP allowlist restricts database access to Fly.io's NAT gateway IPs.

# Get Fly.io outbound IPs for iad region
flyctl ips list --app groundwork-api

# Add to Neon via API or console
# Console: console.neon.tech → Project Settings → IP Allow
# Add each Fly.io IPv4 in CIDR notation: 1.2.3.4/32

# Verify connectivity from a running machine
flyctl ssh console --app groundwork-api
# Inside machine:
psql $DATABASE_URL -c "SELECT version();"

8.3 Content Security Policy

[[headers]]
  for = "/*"
  [headers.values]
    Content-Security-Policy = """
      default-src 'self';
      script-src 'self' 'unsafe-inline' https://browser.sentry-cdn.com;
      style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
      font-src 'self' https://fonts.gstatic.com;
      img-src 'self' data: https://files.groundwork.app;
      connect-src 'self' https://api.groundwork.app https://*.sentry.io
                  https://o4504.ingest.sentry.io;
      frame-ancestors 'none';
      base-uri 'self';
      form-action 'self';
    """

8.4 Rate Limiting

Application-level rate limiting is implemented in the Fastify API using @fastify/rate-limit, backed by in-memory storage at Launch and Upstash Redis at Growth phase.

8.5 IAM Principles

• Fly.io deploy tokens are scoped to individual apps — the GitHub Actions token for groundwork-api cannot deploy to groundwork-workers and vice versa.
• Neon roles: one app_user role with SELECT/INSERT/UPDATE/DELETE on app tables; a separate migrator role with DDL rights used only in CI migrations.
• R2 API tokens: one token scoped to the production bucket with write access; a separate read-only token for presigned URL generation if needed.
• Resend API keys: one per environment (production, staging). Rotate quarterly.

9. Disaster Recovery

10. Launch Checklist

Complete all items before marking the infrastructure as production-ready. Commands assume you are authenticated with Fly.io (flyctl auth login), Netlify (netlify login), and Neon (neonctl auth).

1. 01
   Create Neon project in us-east-1 neonctl projects create --name groundwork --region-id aws-us-east-1 --pg-version 16
2. 02
   Create Neon branches: main, staging, dev neonctl branches create --name staging --parent main and neonctl branches create --name dev --parent staging
3. 03
   Create Fly.io app for API flyctl apps create groundwork-api --org personal, then copy fly.toml from Section 2.2
4. 04
   Create Fly.io app for Workers flyctl apps create groundwork-workers --org personal, then copy fly.toml from Section 2.3
5. 05
   Set all Fly.io secrets for both apps Run flyctl secrets set DATABASE_URL="..." RESEND_API_KEY="..." R2_ACCESS_KEY_ID="..." R2_SECRET_ACCESS_KEY="..." SESSION_SECRET="$(openssl rand -hex 32)" --app groundwork-api
6. 06
   Configure Neon IP allowlist with Fly.io NAT IPs flyctl ips list --app groundwork-api, then add each IP in Neon Console → Project Settings → IP Allow
7. 07
   Run all database migrations against production branch DATABASE_URL_DIRECT="<neon-direct-url>" npm run migrate — verify all migrations succeed with exit code 0
8. 08
   Create Cloudflare R2 production bucket In Cloudflare dashboard → R2 → Create bucket named groundwork-production. Create an API token with Object Read & Write scope restricted to this bucket only.
9. 09
   Connect Netlify site to GitHub repo netlify init in the project root, or connect via Netlify dashboard. Confirm build command is npm run build and publish directory matches netlify.toml.
10. 10
    Set all Netlify environment variables In Netlify dashboard → Site settings → Environment variables: VITE_SENTRY_DSN, VITE_API_BASE_URL=https://api.groundwork.app, VITE_R2_PUBLIC_URL
11. 11
    Configure custom domain on Netlify Netlify dashboard → Domain management → Add custom domain groundwork.app. Point DNS to Netlify's nameservers or add the CNAME/A record as directed.
12. 12
    Configure custom domain on Fly.io API flyctl certs create api.groundwork.app --app groundwork-api. Add the CNAME record to DNS as instructed by the output. Verify with flyctl certs check api.groundwork.app --app groundwork-api.
13. 13
    Add GitHub Actions secrets In GitHub → repo → Settings → Secrets: add FLY_API_TOKEN (from flyctl auth token), NEON_API_KEY, NEON_PROJECT_ID, DATABASE_URL_DIRECT_PROD
14. 14
    Create GitHub Actions environment named "production" with approval gate GitHub → repo → Settings → Environments → New environment → production. Add required reviewers. This gates all production deploys.
15. 15
    First production deploy via GitHub Actions Push to main branch. Verify the workflow completes without errors. Check flyctl status --app groundwork-api shows all machines as started.
16. 16
    Configure Sentry project and verify error reporting Create Sentry project for groundwork. Trigger a test error via the Sentry debug endpoint. Confirm it appears in the Sentry dashboard within 30 seconds.
17. 17
    Set up UptimeRobot monitors for all 5 endpoints Create monitors as listed in Section 6.3. Set alert contacts to on-call email and Slack webhook. Run a test alert to verify delivery.
18. 18
    Verify Neon PITR is active on Pro plan Confirm the project is on the Neon Pro plan (required for PITR). Check Console → Backups to see WAL archiving is enabled and shows recent timestamps.
19. 19
    Run end-to-end smoke test against production Create a test user account, create a project, upload a photo, trigger an email notification, verify it arrives. Check Sentry for zero new errors. Check Fly.io logs for clean request logs.
20. 20
    Document all service account credentials in team password manager Store Neon project ID + admin credentials, Fly.io org slug, Cloudflare Account ID + R2 bucket name, Resend API key, Sentry DSN, and UptimeRobot API key in 1Password or Bitwarden under the "Groundwork Infrastructure" vault.