Merge pull request #27 from adab-tech/claude/globalopportunities-deploy-yukhn1

Bring docs in line with the actual deploy, drop dead Fly.io path

Author: adab-tech

.claude/skills/opportunityfinder-dev/SKILL.md

@@ -410,9 +410,10 @@ Dev deps live in `backend/requirements-dev.txt` (pytest, ruff). Prod deps in
 
 ## Deploy
 
-- **Render** (no CLI): docs/DEPLOY-RENDER.md
-- **Fly.io**: `scripts/deploy-fly.ps1` (app `adab-opportunityfinder`, region lhr);
-  needs `flyctl auth login` or `FLY_API_TOKEN`
+- **Backend (Render)**, no CLI: docs/DEPLOY-RENDER.md
+- **Frontend (Cloudflare Workers)**, edge-served static assets + API proxy:
+  docs/DEPLOY-CLOUDFLARE-WORKERS.md — this is what actually serves
+  `globalopportunities.app` today
 - **Docker local**: `docker compose up --build` (Postgres + API)
 - `/health` returns 503 when the DB is down — platform health checks rely on this.
 - Container runs as non-root `appuser`; keep it that way.

.github/SECRETS.md

@@ -4,23 +4,15 @@ Configure under **Settings → Secrets and variables → Actions** for [adab-tec
 
 | Secret | Required | Purpose |
 |--------|----------|---------|
-| `FLY_API_TOKEN` | For GitHub deploy | Deploy to Fly.io via Actions (`workflow_dispatch`) |
 | `GOOGLE_API_KEY` | Optional | Google Custom Search API (higher quota than scrape fallback) |
 | `GOOGLE_CSE_ID` | Optional | Custom Search Engine ID (pair with `GOOGLE_API_KEY`) |
 
-### Fly.io deploy token
-
-After `flyctl auth login` on your machine:
-
-```powershell
-flyctl tokens create deploy -a adab-opportunityfinder
-gh secret set FLY_API_TOKEN --repo adab-tech/OpportunityFinder
-```
-
-Then run **Actions → Deploy to Fly.io → Run workflow** on GitHub, or use `.\scripts\deploy-fly.ps1` locally.
-
 CI runs without these secrets (SQLite + smoke tests only). For production scraping performance, add both keys from [Google Programmable Search](https://developers.google.com/custom-search/v1/introduction).
 
+Production deploy credentials (Render, Cloudflare) live in each platform's
+own dashboard, not as GitHub Actions secrets — see docs/DEPLOY-RENDER.md and
+docs/DEPLOY-CLOUDFLARE-WORKERS.md.
+
 **Local setup:** copy `backend/.env.example` to `backend/.env` and fill values.
 
 **Sync from local `.env` (run on your machine):**

.github/workflows/deploy-fly.yml

@@ -1,16 +1,16 @@
 # Global Opportunities
 
-Global Opportunities is an AI-assisted opportunity discovery app for scholarships, fellowships, grants, and jobs.
+Global Opportunities is an AI-assisted discovery site for scholarships, fellowships, grants, and jobs — plain-English summaries, real deadlines, refreshed automatically.
 
-## What is included
+**Live:** https://globalopportunities.app
 
-- `backend/` - FastAPI API, database, scraping, and scheduled refresh jobs
-- `frontend/` - static UI that talks to the API
-- `opportunities.db` - local SQLite database used during development
+## Architecture
 
-## Quick start (Windows)
+- `backend/` — FastAPI API, Postgres (via [Neon](https://neon.tech)), scraping/RSS ingest, and scheduled refresh jobs. Deployed on [Render](https://render.com).
+- `frontend/` — static UI, no build step, served from Cloudflare's edge via a Worker (`worker/index.js` + `wrangler.jsonc`). The same worker proxies `/api/*`, `/health`, `/docs`, `/openapi.json`, and `/redoc` to the Render backend, so the browser only ever sees one origin.
+- `admin.html` — analytics + a moderation queue, gated behind email/password admin login (`app/routes/admin_auth.py`).
 
-Double-click `start.bat` in the repo root. The app opens at http://127.0.0.1:8000/ with curated opportunities loaded immediately; a background scrape adds more within a few minutes. Click **Find New** anytime to refresh.
+See [docs/DEPLOY-RENDER.md](docs/DEPLOY-RENDER.md) and [docs/DEPLOY-CLOUDFLARE-WORKERS.md](docs/DEPLOY-CLOUDFLARE-WORKERS.md) for the full deploy story, and [docs/DEPLOY.md](docs/DEPLOY.md) for local development and Docker.
 
 ## Local development
 
@@ -25,48 +25,29 @@ python -m pip install -r requirements.txt
 uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
 ```
 
-### Frontend
-
-Serve the `frontend/` folder with any static web server, then point it at the API.
-
-If the frontend and backend are deployed together on the same domain, the app will use `/api/v1` automatically.
-If they are deployed separately, set the API base before loading `js/app.js`:
-
-```html
-<script>
-  window.OPPORTUNITYFINDER_API_BASE = 'https://your-api-host.example.com/api/v1';
-</script>
-```
+Copy `backend/.env.example` to `backend/.env` first. With nothing else set, the app runs on SQLite and logs alert/save-confirmation emails to the console instead of sending them.
 
-The repo also includes `frontend/config.js` as the deployment hook for that value.
-Edit it when you want to point the static frontend at a separate backend host.
-
-If you are running locally from `file://`, the app falls back to `http://127.0.0.1:8000/api/v1`.
+### Frontend
 
-## Optional search API keys
+Serve `frontend/` with any static web server; it talks to the API at the same origin (`/api/v1`) by default. To point it at a separately-hosted backend, set `window.OPPORTUNITYFINDER_API_BASE` in `frontend/config.js`.
 
-`backend/.env.example` includes optional Google Custom Search settings:
+### Windows quick start
 
-- `GOOGLE_API_KEY`
-- `GOOGLE_CSE_ID`
+Double-click `start.bat` — creates a venv, installs backend dependencies, and opens the app at http://127.0.0.1:8000/. Local only, not how production runs.
 
-Without those keys, the scraper falls back to public search scraping.
+## Optional discovery API keys
 
-## Deploy to the web
+`backend/.env.example` documents `GOOGLE_API_KEY` / `GOOGLE_CSE_ID` (Google Custom Search) and `YOU_API_KEY` (You.com) — both optional. Without them, the scraper falls back to public search scraping.
 
-**Recommended:** one container serves the UI and API on the same domain (simplest for users).
+## Email alerts
 
-| Method | Guide | CLI needed? |
-|--------|--------|-------------|
-| **Render** (easiest public URL) | [docs/DEPLOY-RENDER.md](docs/DEPLOY-RENDER.md) | No — GitHub + dashboard |
-| Fly.io | [docs/DEPLOY.md](docs/DEPLOY.md) | Yes (`flyctl auth login`) |
-| Docker + Postgres locally | `docker compose up --build` → http://localhost:8000 | Docker Desktop |
+Alert and save-confirmation emails are logged to the console by default — no provider required to run or test the feature end-to-end. Set `RESEND_API_KEY`, `BREVO_API_KEY`, or `SENDGRID_API_KEY` to send them for real; see `backend/app/services/email_sender.py`.
 
-Production uses **PostgreSQL** (`DATABASE_URL`) and **RSS feeds** for reliable ingest (ReliefWeb, Scholars4Dev, Opportunity Desk, and more). Optional Google CSE keys still improve discovery.
+## Tests
 
-## Production notes
+```powershell
+cd backend && python -m pytest tests -v
+cd frontend && npm test
+```
 
-- Set `DATABASE_URL` to Postgres in production (see `docker-compose.yml` or Fly Postgres).
-- `ENABLE_SCHEDULER=true` on a single instance runs periodic RSS + scrape jobs.
-- `CORS_ORIGINS` defaults to `*`; restrict when the frontend is on another host.
-- Health: `GET /health` (used by Fly.io checks).
+CI (`.github/workflows/ci.yml`) runs both suites plus `ruff` lint on every push/PR to `main`.

README.md

@@ -1,14 +1,19 @@
-# Move the frontend to Cloudflare Workers (edge-served static assets)
+# Cloudflare Workers (edge-served static assets)
 
-Today, `globalopportunities.app` is a Cloudflare-proxied DNS record pointing
-at the Render service, which serves both the API and the static frontend
-(`frontend/`) from one Docker container. Every visitor's HTML/CSS/JS still
-makes a round trip to Render's origin server (and can hit a cold start on
-Render's free tier if it's been idle).
+**This is live in production.** `globalopportunities.app` is a Cloudflare
+Worker (`worker/index.js` + `wrangler.jsonc`) that serves the static frontend
+(`frontend/`) from the edge and proxies API calls to the Render backend
+server-side. This doc is kept as the reference for how that's set up and for
+reproducing it (e.g. a fresh Cloudflare account, or a new environment).
 
-This moves the static frontend onto Cloudflare's edge network instead —
-faster worldwide, and immune to Render cold-starts for anything that isn't
-an API call — **without touching the backend or admin auth at all.**
+Before this move, `globalopportunities.app` was a Cloudflare-proxied DNS
+record pointing directly at the Render service, which served both the API
+and the static frontend from one Docker container — every visitor's
+HTML/CSS/JS made a round trip to Render's origin server, with a possible
+cold start on Render's free tier if it had been idle. Moving the static
+frontend onto Cloudflare's edge network instead is faster worldwide, and
+immune to Render cold-starts for anything that isn't an API call — **without
+touching the backend or admin auth at all.**
 
 > **Why "Workers" and not "Pages"?** Cloudflare's own current guidance:
 > "If you are starting a new project, use Workers instead of Pages. Pages

docs/DEPLOY-CLOUDFLARE-WORKERS.md

@@ -33,6 +33,14 @@ No local CLI required — deploy from the Render dashboard in ~5 minutes.
 
 ## Custom domain — globalopportunities.app
 
+**This is no longer how the live domain is wired up.** `globalopportunities.app`
+now points at a Cloudflare Worker that serves the frontend from the edge and
+proxies API calls to this Render service — see
+[DEPLOY-CLOUDFLARE-WORKERS.md](DEPLOY-CLOUDFLARE-WORKERS.md) for the actual
+current setup. The steps below are kept for reference if you ever want to run
+this backend standalone, pointed at directly by DNS instead of through the
+Worker.
+
 In the Render web service → **Settings → Custom Domains**, add both:
 
 - `globalopportunities.app` (apex)
@@ -60,8 +68,9 @@ so the app's own links point at the real domain instead of localhost:
 |----------|-------|
 | `PUBLIC_BASE_URL` | `https://globalopportunities.app` |
 
-(`CORS_ORIGINS` can stay `*` — the frontend is served same-origin from this
-same service, so it isn't relying on cross-origin CORS.)
+(`CORS_ORIGINS` can stay `*` — the frontend is served from Cloudflare's edge
+via a Worker that proxies API calls back to this service server-side, not by
+the browser making cross-origin requests; see docs/DEPLOY-CLOUDFLARE-WORKERS.md.)
 
 ## Free tier notes
 

docs/DEPLOY-RENDER.md

@@ -1,90 +1,37 @@
-# Deploy OpportunityFinder
+# Deploy Global Opportunities
 
-One domain, one container: FastAPI serves `/api/v1` and the static `frontend/` on the same origin (no CORS headaches).
+Production is two pieces: the **backend** (FastAPI + Postgres) on Render, and the **frontend** (static, no build step) on Cloudflare Workers at the edge, which proxies API calls back to Render so the browser only ever sees one origin. See:
 
-## Option A — Docker Compose (local production test)
+- [DEPLOY-RENDER.md](DEPLOY-RENDER.md) — backend + database, from zero to a live URL
+- [DEPLOY-CLOUDFLARE-WORKERS.md](DEPLOY-CLOUDFLARE-WORKERS.md) — moving the frontend to the edge and wiring up the custom domain
+
+This doc covers local development only.
+
+## Docker Compose (local, with Postgres)
 
 Requirements: [Docker Desktop](https://www.docker.com/products/docker-desktop/)
 
-```powershell
-cd "C:\Users\Adamu\Desktop\Project 101"
+```
 docker compose up --build
 ```
 
 Open **http://localhost:8000/** — Postgres runs in the `db` service; data persists in the `pgdata` volume.
 
 Stop: `docker compose down` (add `-v` to wipe the database).
 
-## Option B — Fly.io (public URL)
-
-1. Install the [Fly CLI](https://fly.io/docs/hands-on/install-flyctl/) and run `fly auth login`.
-2. From the repo root:
-
-**One-command deploy** (after `fly auth login`):
-
-```powershell
-cd "C:\Users\Adamu\Desktop\Project 101"
-.\scripts\deploy-fly.ps1
-```
-
-App name: **`adab-opportunityfinder`** → **https://adab-opportunityfinder.fly.dev**
-
-Manual steps (equivalent):
-
-```powershell
-fly launch --no-deploy --name adab-opportunityfinder --region lhr
-fly postgres create --name adab-opportunityfinder-db --region lhr --vm-size shared-cpu-1x --volume-size 1
-fly postgres attach adab-opportunityfinder-db -a adab-opportunityfinder
-fly deploy -a adab-opportunityfinder
-fly open -a adab-opportunityfinder
-```
-
-`DATABASE_URL` from Fly Postgres is normalized automatically for SQLAlchemy + psycopg2.
-
-### Custom domain on Fly
-
-```powershell
-fly certs add finder.yourdomain.com
-```
-
-Point DNS (CNAME) to the hostname Fly prints. HTTPS is automatic.
-
-## Option C — Railway / Render
-
-1. Create a **PostgreSQL** database on the platform.
-2. Deploy from this GitHub repo (`adab-tech/OpportunityFinder`) with:
-   - **Build:** Dockerfile at repo root
-   - **Start:** handled by Dockerfile (`PORT` is set by the platform)
-3. Environment variables:
-
-| Variable | Value |
-|----------|--------|
-| `DATABASE_URL` | Postgres URL from the provider (use `postgresql+psycopg2://...` if needed) |
-| `ENABLE_SCHEDULER` | `true` (only on **one** instance if you scale horizontally) |
-| `CORS_ORIGINS` | `*` or your static site origin if split later |
-
-## Split frontend later (optional)
-
-By default the UI uses same-origin `/api/v1`. To host the UI on GitHub Pages and API elsewhere, set in `frontend/config.js` before deploy:
-
-```javascript
-window.OPPORTUNITYFINDER_API_BASE = 'https://your-api.fly.dev/api/v1';
-```
-
-And set `CORS_ORIGINS` on the API to your Pages URL.
-
 ## Environment reference
 
-Copy `backend/.env.example` to `backend/.env` for local dev.
+Copy `backend/.env.example` to `backend/.env` for local dev. Full definitions live in `backend/app/config.py`; highlights:
 
 | Variable | Purpose |
 |----------|---------|
 | `DATABASE_URL` | SQLite locally; Postgres in production. Prefer [Neon](https://neon.tech)'s free tier over a platform's own free Postgres (e.g. Render) — Render's free Postgres auto-deletes the database 30 days after creation, which has already caused a production outage; Neon's free tier only autosuspends compute when idle and never deletes data. |
-| `ENABLE_SCHEDULER` | Background RSS + scrape jobs |
-| `CORS_ORIGINS` | Comma-separated origins, or `*` |
-| `PORT` | Set by Fly/Railway/Render (uvicorn listens here) |
-| `GOOGLE_API_KEY` / `GOOGLE_CSE_ID` | Optional; improves discovery |
+| `ENABLE_SCHEDULER` | Background RSS + scrape jobs — set `true` on exactly one instance if you scale horizontally. |
+| `CORS_ORIGINS` | Comma-separated origins, or `*`. |
+| `GOOGLE_API_KEY` / `GOOGLE_CSE_ID` / `YOU_API_KEY` | Optional; improve discovery beyond the scraping fallback. |
 | `RESEND_API_KEY` / `BREVO_API_KEY` / `SENDGRID_API_KEY` | Optional; unset means alert/save-confirmation emails are logged, not sent. If more than one is set, Resend takes priority, then Brevo. |
+| `ADMIN_EMAIL` / `ADMIN_PASSWORD_HASH` / `SESSION_SECRET_KEY` | Required together for admin login (analytics + moderation queue). Generate the hash with `backend/scripts/hash_admin_password.py`. Unset means admin endpoints refuse every request. |
+| `PUBLIC_BASE_URL` | Builds the manage-your-alerts link in outgoing emails; set to your real domain in production. |
 
 ## Health check
 
@@ -95,12 +42,6 @@ Copy `backend/.env.example` to `backend/.env` for local dev.
 
 1. DB tables created if missing.
 2. Curated seeds if the database is empty.
-3. RSS ingest from stable feeds (ReliefWeb, Scholars4Dev, Opportunity Desk, etc.).
+3. RSS ingest from stable feeds (ReliefWeb, Scholars4Dev, Opportunity Desk, and more).
 4. Background scrape if fewer than ~25 active listings.
 5. Scheduler (every 6h by default) if `ENABLE_SCHEDULER=true`.
-
-## Next steps (product)
-
-- Domain registered: `globalopportunities.app` — see docs/DEPLOY-RENDER.md for the custom-domain DNS steps.
-- Add email alerts (Resend + saved searches).
-- Add Meilisearch for faster full-text search at scale.