Deploying a Frontend and a Backend

# Frontend on Vercel — no config needed for the common case
#   push to main      -> production build and deploy
#   push to a branch  -> a preview URL, per commit
#   build command: next build; env vars per environment
# Rollback is instant, because previous builds stay served.

# Backend on Fly — a container, and migrations
# fly.toml
[deploy]
  release_command = "alembic upgrade head"    # runs BEFORE the new
                                              # version takes traffic
[http_service]
  internal_port = 8000
  auto_stop_machines = "suspend"
  min_machines_running = 1                    # 0 means cold starts

[[http_service.checks]]
  path = "/health"                            # unhealthy -> no traffic

# .github/workflows/deploy.yml
- run: flyctl deploy --remote-only
  env: { FLY_API_TOKEN: '${{ secrets.FLY_API_TOKEN }}' }

# A release_command failure aborts the deploy and the old version
# keeps serving — which is exactly what you want from a bad migration.

# Health check discipline: /health should verify the database, and
# a deploy should not be considered done until it passes.

// After a deploy, browsers with the page already open keep running
// the PREVIOUS bundle — for minutes, or hours on a left-open tab.
// So for a while, old frontend + new backend are talking to each
// other. That window dictates the rules:

//   1. Deploy the BACKEND first, additively. The new API must still
//      serve the old frontend.
//   2. Only then deploy the frontend that uses the new fields.
//   3. Remove the old fields in a LATER release, once no old bundle
//      can still be running.

// The expand / migrate / contract sequence for a rename:
//   release 1  add the new column, write to both, read the old
//   release 2  backfill; frontend starts reading the new one
//   release 3  stop writing the old; drop it

// Doing it in one step means every open tab breaks the moment the
// migration lands.

// Migrations that are safe online:  ADD COLUMN (nullable, no default
//   scan), CREATE INDEX CONCURRENTLY, adding a table.
// Migrations that lock:  ALTER COLUMN TYPE, adding NOT NULL to a
//   populated table, a non-concurrent index on a large table.

// Handle the stale bundle explicitly: a lazy chunk from the previous
// build 404s after deploy. Catch it and offer a reload rather than
// showing a broken page (see the React lazy-routes concept).

# Frontend rollback is instant — promote a previous deployment.
vercel rollback <url>

# Backend rollback is a redeploy of the previous image:
flyctl releases -a tool-hub-api
flyctl deploy --image registry.fly.io/tool-hub-api@sha256:...

# But a migration does NOT roll back with it. A dropped column is
# gone, and the previous code expects it. This is the real reason
# migrations must be additive: rollback is only possible if the old
# code still works against the new schema.

# Before any risky release:
#   - a database backup you have actually restored once
#   - the migration tested against a copy of production data
#   - a feature flag, so the new path can be turned off without a
#     deploy
if flags.enabled("new_scoring", user):  ...

# After every release, watch for five minutes:
#   error rate, p95 latency, 4xx/5xx mix, and one business metric
#   (signups, submissions) — the last catches "no errors, but nobody
#   can complete checkout".

# Deploy on a Tuesday morning, not a Friday evening. The mechanism is
# not the risk; being unavailable when it misbehaves is.