# SideGuy → Vercel/Neon (or Netlify/DB) Transition Evaluation

**Date:** 2026-05-07
**Author:** Claude (with PJ)
**Status:** Recommendation — DO NOT migrate to Vercel/Neon stack now. Add a thin Cloudflare D1 + Workers layer instead for the real gaps.

---

## TL;DR

> **The current stack (S3 + CloudFront + Cloudflare Worker + static HTML + Python ship scripts) is doing exactly what SideGuy needs. SSR/DB stack would ADD complexity without unlocking new value.**

The migration question is the right one to *ask* every 6 months — but the answer right now is "not yet, and possibly never."

**Three reasons:**

1. **SideGuy is not dynamic.** Every visitor sees the same content. SSR + DB only pays off when content varies per user (auth, personalization, dashboards, real-time). The encrypted dashboard is the only auth-gated surface, and it's already solved with client-side AES-GCM decrypt.

2. **The current stack already wins on the dimensions that matter.** Cost (~$5/mo total), uptime (CloudFront 99.99%), iteration speed (PJ ships an HTML file in 30 sec), realtime SEO (1pm DM → 1:45pm indexed page), and git-as-undo simplicity (any change reversible with `git checkout`).

3. **The real gaps are tiny and don't need Vercel.** Cross-device dashboard state, lead persistence, send history — all solvable with **Cloudflare D1 (SQLite at edge) + Workers** that already exist in the stack via the email worker.

**What to actually do:** Phase 1 of the counter-proposal below — add a Cloudflare D1 database for leads + dashboard state. ~3 days of work, $0/mo cost, zero migration risk to the 6,000+ static pages.

---

## Current Stack Snapshot

| Layer | Implementation | Cost | Strengths |
|---|---|---|---|
| **Origin storage** | S3 (`sideguysolutions-site`) | Pennies/mo | Versioning, durability, simple `aws s3 cp` deploy |
| **CDN / edge** | CloudFront `E3JL4IBM4SVI56` | ~$1-3/mo | Global low-latency, caching, custom error pages |
| **DNS / domain** | Cloudflare (zone under Petezonis@gmail.com) | Free | Apex → www path-preserved 301, page rules |
| **Email send** | Cloudflare Worker `sideguy-send-email` + Resend API | $0 (Worker free tier) + Resend ~$0 | Serverless, encrypted secrets, CF Access gate |
| **Email auth gate** | Cloudflare Access (Petezonis@gmail.com only) | Free | OAuth via CF, no app-side auth code needed |
| **News watcher** | Python cron (`0 4,13,18 * * *`) on PJ's Mac → `dashboard/news-alerts.json` → S3 → CF invalidate | $0 | Simple, debuggable, auto-deploys |
| **Pages** | 6,000+ static HTML, inline CSS, schema.org markup | $0 | Portable, fast TTFB, SEO-perfect |
| **Encrypted dashboard** | Client-side AES-256-GCM (PBKDF2-SHA256 250k iter) on `network.html` | $0 | Web Crypto API, no server, no auth backend |
| **Lead state** | `data/leads.csv` (33+ rows) + `data/dms/<slug>.md` markdown files | $0 | Git-versioned, human-readable, no DB to maintain |
| **Ship workflow** | Python BeautifulSoup ship scripts (`_ship*.py`) → `aws s3 sync` → CF invalidate | $0 (PJ's Mac compute) | Idempotent, reversible via git |
| **Dev environment** | Mac local, occasional GitHub Codespaces | $0 | No vendor lock-in |

**Total monthly cost: ~$5/mo.** Mostly S3 + CloudFront bandwidth. Often less.

**Total page count under management:** ~6,000+ HTML files in root + `/shareables/` + cluster pages.

**Engineering team:** 1 (PJ) + AI collaboration.

---

## Vercel + Neon Path — Honest Evaluation

### What you'd gain

- **Database-driven content.** Postgres for leads, prospects, news, send history.
- **Server-Side Rendering.** Faster TTFB on dynamic pages (none of which currently exist on SideGuy).
- **API routes.** REST/RPC endpoints colocated with the frontend code.
- **Edge functions.** Cheap globally distributed compute via Vercel Edge Runtime.
- **Auto-deploy on git push.** Vercel watches main, builds + deploys.
- **Preview deployments.** Each PR gets a preview URL.
- **Built-in observability.** Vercel Analytics, Web Vitals, function logs.

### What you'd lose

- **The 6,000+ static page workflow.** Moving from `aws s3 cp page.html s3://bucket/page.html` to a Next.js deploy means:
  - Each page becomes a route file or markdown file in the framework
  - Inline CSS becomes problematic at 6,000-page scale (CSS-in-JS or global stylesheets)
  - SEO meta + schema.org JSON-LD must be templated through Next.js Head/Metadata API
  - The "raw HTML portability" doctrine — sending pages as standalone files — breaks
- **Realtime SEO speed.** Currently a 1pm DM produces a 1:45pm indexed page. Vercel deploys take 30s-5min depending on build size. Indexing is unaffected, but the *ship* step gets slower.
- **Git-as-undo simplicity.** `git checkout -- *.html` no longer rolls back DB state. Need migration discipline + backup strategy.
- **CDN-cache wins.** CloudFront on a 5-minute TTL serves cached HTML at <50ms TTFB globally. Vercel SSR cold starts can hit 200-800ms.
- **Vendor lock-in flexibility.** Currently you can leave AWS or Cloudflare in a day. Vercel/Neon is a deeper integration.

### Costs

| Item | Free tier | Likely Pro tier | Notes |
|---|---|---|---|
| Vercel hosting | 100GB bandwidth/mo, 100k function invocations/mo, 1 team member | $20/seat/mo + overages | High-impression sites can blow free fast |
| Neon Postgres | 3GB storage, 1 compute, branching limited | $19+/mo | Free tier is fine for leads-sized data |
| Vercel Image Optimization | 1k transformations/mo | $0.50 per 1k | Currently $0 — you don't optimize images |
| Vercel Analytics | 25k events/mo | $10+/mo | Currently use GSC |
| **Realistic monthly** | $0 (if free tiers hold) | **$40-100/mo** | vs current $5/mo |

### Migration effort estimate

| Phase | Time | Risk |
|---|---|---|
| Set up Next.js project, port homepage + 5 key pages | 1 week | Low |
| Build CMS layer for shareables (markdown → page) | 1-2 weeks | Medium — schema/SEO edge cases |
| Migrate 6,000 static pages to component templates | **3-6 weeks of focused work** | **High — every page has unique inline CSS, schema, layout** |
| Build database layer (leads, dms, news) + auth | 2 weeks | Medium — auth replacement for AES dashboard is non-trivial |
| Migrate encrypted dashboard to NextAuth + DB-backed | 1-2 weeks | High — current encryption doctrine is well-understood, replacing it loses clarity |
| QA + parallel-run + cutover | 2 weeks | High — realtime SEO doctrine must survive |
| **Total realistic effort** | **9-13 weeks of focused engineering** | **~$15-30k of contract eng time, or 3 months of PJ's calendar** |

### Verdict on Vercel/Neon

**Cost-benefit doesn't justify the migration today.** You'd spend 3 months and $0-30k to gain features that don't address SideGuy's real bottlenecks. The bottleneck right now is *outreach response rate*, not page-architecture flexibility.

---

## Netlify + Postgres Path — Honest Evaluation

Largely the same trade-offs as Vercel + Neon, with these differences:

### Differences from Vercel

- **Netlify Functions** are AWS Lambda under the hood (cold-start prone) vs Vercel's Edge Runtime
- **Netlify is slightly cheaper** at the small tier ($19/mo Pro)
- **Less React/Next.js opinionation** — friendlier to Eleventy / Astro / Hugo (more in keeping with static-first ethos)
- **Build time included** in plan — Vercel charges per build minute past 6000/mo
- **DB partner choice** — Netlify partners with Supabase, Neon, Fauna; you pick

### Where Netlify might be a better fit IF migrating

If a migration becomes necessary later, **Netlify + Astro + Supabase** would be the more SideGuy-shaped choice:
- **Astro** generates static HTML by default (matches current ethos), opts into SSR per-page
- **Supabase** is open-source Postgres + auth + storage (replaces 3 vendors with one)
- **Netlify** lets you partial-deploy (only changed files redeployed) — closer to current `aws s3 cp` mental model

### Verdict on Netlify

If we ever migrate, **Astro on Netlify with Supabase** is the better destination than Next.js on Vercel with Neon. But same conclusion: not worth it now.

---

## Counter-Proposal: Enhanced Current Stack

Instead of migrating, **add a thin database + state layer to the existing stack** to solve the actual gaps.

### Real gaps in the current stack

1. **`data/leads.csv` is brittle for multi-device editing.** If PJ marks a lead "sent" on his phone and another action on his laptop, last-write-wins corrupts state.
2. **Dashboard `localStorage` state doesn't sync.** Snooze status, cleared-for-now flags, focus-mode preferences are per-browser only.
3. **Email send history lives in CSV notes.** Hard to query "emails sent in last 7 days" or "reply rate by template."
4. **News-alerts.json is overwritten on every cron run.** Lose history of what triggered when.
5. **No audit trail for outreach.** Can't answer "what message did I send to this person on Apr 28?" without grep through `data/dms/`.

### Solution: Cloudflare D1 + Workers (you already have a Worker)

| Layer | What it solves | Cost | Effort |
|---|---|---|---|
| **Cloudflare D1** (SQLite at edge) | Replace `data/leads.csv` with a queryable database. Cross-device sync. Audit trail. | Free up to 5M reads/mo, 100k writes/day | 2-3 days to set up + migrate CSV |
| **New Worker `sideguy-state`** | API endpoints: `GET /leads`, `POST /leads/:id/status`, `POST /snooze` | Free | 2 days |
| **Worker KV for dashboard prefs** | Cross-device snooze + filter state | Free up to 1k writes/day | 1 day |
| **Worker for email send history** | Append-only log of every send (recipient, template, timestamp, response status) | Free | 1 day |
| **Total** | — | **$0/mo** | **~1 week** |

### What stays the same

- All 6,000+ static pages — untouched
- CloudFront + S3 origin — untouched
- Realtime SEO loop — untouched
- Encrypted dashboard — untouched (just fetches state from new Worker)
- Git workflow — untouched
- Python ship scripts — untouched

### What gets better

- Multi-device dashboard editing (laptop + phone in sync)
- Queryable lead history (real reporting on reply rates, time-to-reply, etc.)
- Real audit trail (every send/edit/snooze logged with timestamp + actor)
- Dashboard `localStorage` becomes a fallback, not the source of truth
- News history retained (when did we first see this signal? did we act on it?)

### What this enables down the road

- A simple "operator metrics" page (`/dashboard/metrics`) showing real reply rates per cluster
- A real "sent a page" indicator that survives cache clears
- Easier to build a member portal LATER if it becomes a real need (D1 + Worker auth is a known pattern)
- Simple cross-prospect linking (e.g., "Riley Stricklin → Cadre AI → connected with 4 other prospects via Cadre intro")

---

## Decision Matrix — When Each Path Is Right

| Trigger | Right move |
|---|---|
| **You're at <10k pages, 1 operator, no auth-gated content** | Stay on current stack ✅ (today) |
| **You add a Cloudflare D1 layer + Worker** | Counter-proposal Phase 1 — solves real gaps |
| **You hit 100k pages and the manual ship workflow breaks down** | Consider Astro + Netlify (static-first, matches ethos) |
| **You add a paid member portal with logins + per-user content** | Astro + Supabase OR Next.js + Vercel becomes worth the effort |
| **You hire a frontend engineer who knows React** | Consider Vercel + Next.js for tooling familiarity |
| **You build a real-time multiplayer feature (live editing, multi-operator dashboard)** | Vercel + WebSockets / Supabase realtime |
| **You need EU/data-residency compliance (GDPR strict mode)** | Cloudflare Workers (region picking) or Vercel Pro (data regions) |

The takeaway: **stay on the current stack until a specific trigger fires.** SSR/DB stack solves problems SideGuy doesn't yet have.

---

## If You Decide to Migrate Anyway — Migration Phases

For completeness. Recommended order if/when migration becomes the right call:

### Phase 0 — Pre-flight (1 week)

- Inventory: page count, total bandwidth/mo, GSC top 100 pages, current automated workflows
- Architectural decisions: Astro vs Next.js, Supabase vs Neon, deploy target
- Set up new repo + new project + a single test page that mirrors current homepage
- Configure DNS for staging subdomain (e.g., `staging.sideguysolutions.com`)

### Phase 1 — Static migration (3-6 weeks)

- Port static page templates (homepage, shareable, problem-page, money-page, cluster-pillar)
- Build a CMS layer that reads existing markdown / HTML files into the new framework
- Migrate top-100 GSC pages first (preserve canonical URLs + metadata)
- Set up monitoring to catch SEO regressions during cutover
- Run NEW stack in parallel with OLD stack on staging subdomain

### Phase 2 — Dynamic features (2-3 weeks)

- Build `/dashboard` route with auth (NextAuth or Supabase Auth)
- Migrate `data/leads.csv` to Postgres schema
- Migrate `data/dms/*` to a `dms` table
- Wire Cloudflare Worker email send through new API layer (or replace with Supabase Edge Function)
- Migrate news_watcher to a Vercel Cron or Supabase Edge Function

### Phase 3 — Cutover (2 weeks)

- DNS flip: `www.sideguysolutions.com` points to Vercel/Netlify
- Old S3 origin stays live for 30 days as fallback
- Monitor GSC for 72h post-cutover for indexing changes
- 301-redirect any URL pattern changes (shouldn't be any if done right)
- Decommission CloudFront + S3 after 30-day verification window

### Phase 4 — Cleanup (1 week)

- Archive old GitHub repo state
- Update `CLAUDE.md` with new architecture
- Update all ship scripts + tooling for new deploy mechanism
- Update `tools/encrypt_dashboard.py` for new auth flow

**Total: 9-13 weeks of focused work.**

---

## Honest Closing Note

PJ — you asked the right question. Asking "should we migrate?" every 6 months keeps the architecture honest.

But the answer right now is **no**, because:

1. The current stack is still under-leveraged. There are pages not yet shipped, GSC opportunities not yet captured, prospects not yet contacted. Migration spends engineering time you'd otherwise spend compounding.

2. SSR/DB stack solves problems you don't have. Per-user dynamic content is not a SideGuy use case yet.

3. The realtime SEO doctrine — your moat — depends on the speed of static HTML deploys. Migration *slows* that down.

4. The real gaps (cross-device state, lead persistence, audit trail) are solvable with Cloudflare D1 + Workers in ~1 week, $0/mo, zero risk to the static pages.

**My recommendation:** Phase 1 of the counter-proposal — add Cloudflare D1 for leads + Worker for state sync. Park the Vercel/Neon question for 6 months. Re-evaluate when one of the decision-matrix triggers fires.

When you're ready to do the D1 + Worker layer, I can scope + ship it as a real plan with concrete tasks. Just say the word.

🤘