🔎 Opportunity Hunter

An AI agent that hunts for jobs so you don't have to. Tell it what you want once — it continuously searches live listings, scores every match 0–100 against your profile, explains why it fits, and tracks each one from saved to offer.

🌐 Live: opportunityhunter.xyz

---

Highlights

• Semantic matching — skills and roles are compared by meaning using Voyage embeddings, so a "React" skill matches a "Next.js" listing. Degrades gracefully to exact-text matching with no API key. → how it works
• Explainable scores — every 0–100 score ships with what matched, what's missing, and cross-domain guards so a doctor's profile never matches a developer role.
• Autonomous agent — profile → query → fetch → de-duplicate → score → explain → notify, on a schedule, whether or not you're logged in.
• Profession-agnostic — works for nurses, analysts and designers, not just engineers.
• A complete product — authentication, onboarding, an application tracker, email digests, Razorpay billing and an admin surface.

Run it

npm install
npm run dev

Open http://localhost:3000. Demo account: [email protected] / demo1234 (Pro plan, admin).

npm run check type-checks and runs the matching-engine self-test.

Stack

Next.js 15 (App Router, server actions) · SQLite via better-sqlite3 (file at ./data/app.db, schema auto-created) · Tailwind v4 · hand-rolled sessions (Node crypto.scrypt, httpOnly cookie).

Layout

Path	What
src/lib/ai/index.ts	parseSearchProfile, generateSearchQueries, normalizeOpportunity, deduplicateOpportunities, calculateMatchScore, generateMatchExplanation, recommendNextAction, generateDailyDigest — pure, deterministic, swappable for an LLM per function
src/lib/agent.ts	The Opportunity Hunter Agent: profile → queries → sources → normalize → dedupe → score → explain → save → notify. Enforces free-plan limits server-side
src/lib/sources/	SourceAdapter interface + registry. jsearch.ts is the live feed; demo.ts (30 fictional listings) is now only the engine's test fixture
src/lib/boot.ts	Seeds the demo account; runs due hunts every 15 min in-process. POST /api/cron/hunt (Bearer CRON_SECRET) for external schedulers
src/lib/email.ts	EmailProvider — console by default, Resend when RESEND_API_KEY is set
src/lib/plans.ts	Plan definitions and weekly discovery caps
src/app/actions.ts	All server actions (auth, profile, save/reject/apply, tracker, alerts, billing, admin)

Integrations (all optional, see .env.example)

• Google login: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET. Button appears automatically.
• Email: RESEND_API_KEY. Otherwise digests and reset links print to the server console.
• Payments: RAZORPAY_KEY_ID + RAZORPAY_KEY_SECRET turn on checkout. Pro is a 30-day pass (₹499, no auto-renew; buying again stacks), expired every 15 min in boot.ts. Add a Razorpay webhook to /api/razorpay/webhook for event order.paid with secret RAZORPAY_WEBHOOK_SECRET, so buyers who close the tab mid-payment still get Pro. Logic in src/lib/razorpay.ts; admins can still set plans manually at /admin.
• Live job listings: RAPIDAPI_KEY enables the JSearch adapter (src/lib/sources/jsearch.ts) — a licensed aggregator that includes LinkedIn, Indeed and Glassdoor postings. LinkedIn has no third-party search API and forbids scraping, so this is the legitimate route. Add further adapters in src/lib/sources/index.ts.
• Semantic matching: VOYAGE_API_KEY upgrades the matcher from exact text to meaning (see below).

How matching works

calculateMatchScore (src/lib/ai/index.ts) is a deterministic, explainable scorer: skills, role, experience, location and salary each produce a 0–100 sub-score, combined by fixed weights into one number with a plain-English breakdown. It is synchronous and runs in a hot loop over every candidate, so it never makes a network call.

By default skills and roles are matched by normalized text, which misses obvious equivalences — "React" vs "Next.js", "Postgres" vs "PostgreSQL". Setting VOYAGE_API_KEY adds a semantic layer (src/lib/ai/embeddings.ts):

• Every skill, role and listing description is embedded once via Voyage and cached in SQLite (embeddings table), keyed by text. Vectors are unit-normalized, so similarity is a dot product.
• warmForScoring(profile, opps) embeds any new strings up front (async, batched); callers await it before scoring. The scorer then reads warmed vectors synchronously — it stays a pure function.
• A required skill counts as covered if an exact match or a profile skill within SKILL_SIM cosine; a title earns a semantic role floor above ROLE_SIM; and whole-profile-vs-listing similarity is a small ±nudge on the final score. Cross-domain guards still apply (a doctor never matches a dev role).
• No key → the semantic helpers return null and the matcher falls back to exact text, so the app and its self-tests run fully offline. npm run check exercises the fallback; with a key set it also asserts related skills out-score unrelated ones.

Deploying

Needs a long-running Node server with a persistent disk — Railway, Render, Fly.io or a VPS. It will not work on serverless hosts (Vercel, Netlify): the SQLite file would be wiped between invocations and the in-process scheduler would never fire.

npm ci && npm run build && npm start

Required settings:

Variable	Why
DATABASE_PATH	Point at a mounted volume, e.g. /data/app.db. Anything else is lost on redeploy.
ADMIN_EMAILS	Your email. There is no default admin in production.
APP_URL	Public URL — used in digest links and the Google OAuth callback.

Production checklist

The app is a single Node process + persistent disk. Walk this list before inviting strangers.

1. Host — Railway / Render / Fly / VPS. Not Vercel. DATABASE_PATH on a volume. Exactly one instance, or disable the in-process scheduler and hit POST /api/cron/hunt.
2. Inventory — RAPIDAPI_KEY. Without it the live pool is empty. Watch RAPIDAPI_MONTHLY_CALLS.
3. Email — Gmail app password or Resend + EMAIL_FROM. Otherwise digests and reset links stay in the server log.
4. Admin — ADMIN_EMAILS set; SEED_DEMO off unless you want the published demo password live.
5. Payments (optional) — RAZORPAY_KEY_ID + RAZORPAY_KEY_SECRET + webhook secret on /api/razorpay/webhook for order.paid. RAZORPAY_INTERNATIONAL=true for $10 outside India.
6. Resume import (optional) — ANTHROPIC_API_KEY.
7. Copy — Pro is a 30-day pass: unlimited matches + digest. There is still one search profile per user.

Doctor, nurse and other non-software titles search JSearch as those titles (not as “X engineer”). Scoring will not treat a software listing as a match for a physician profile.

Run exactly one instance. The scheduler and rate limiter live in process, so a second instance would double-hunt and halve the rate limits. To scale out, disable the in-process scheduler and drive POST /api/cron/hunt (Bearer CRON_SECRET) from an external scheduler instead.

The demo account is not created in production unless SEED_DEMO=true; its password is published in this repo, so treat any instance that enables it as public.

Search engines

Public pages (/, /pricing, /terms, /privacy, /refunds, /contact) are listed in src/lib/site.ts with their last-modified dates; that list feeds /sitemap.xml, canonical URLs and the structured data. Each public page passes its own description to pageMetadata(). Login, sign-up, password resets, onboarding and everything behind login send noindex, and /robots.txt (src/app/robots.ts) disallows them and /api/. htmlLimitedBots in next.config.ts makes Next put the title, description and canonical in <head> for every user agent instead of streaming them into <body>. When you add a public page, add it to PUBLIC_PAGES and link it from SiteFooter; when you change a public page's text, bump its lastModified. To verify the site in Google Search Console with an HTML tag, set GOOGLE_SITE_VERIFICATION.

Future categories

opportunities.category and search_profiles.category default to job. The agent, scoring and UI are category-agnostic apart from job-specific fields, so freelance/scholarship/grant sources can be added as new adapters later.