Joben Resume

Joben Resume is an AI-assisted resume builder SaaS built with Next.js App Router, TypeScript, Supabase, Clerk, Stripe, Resend, Upstash, and Anthropic.

Core Features

• Resume builder with ATS-focused scoring
• AI review and bullet improvement workflows
• Cover letter generation and PDF export
• Subscription upgrades (Stripe)
• Automated welcome and follow-up emails
• Operational observability via health endpoint, webhook idempotency, and email/event tracking

Local Development Setup

1) Install dependencies

npm install

2) Configure environment variables

Create .env.local and define all required values:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
• CLERK_SECRET_KEY
• CLERK_WEBHOOK_SECRET
• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY
• UPSTASH_REDIS_REST_URL
• UPSTASH_REDIS_REST_TOKEN
• ANTHROPIC_API_KEY
• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET
• STRIPE_PRO_PRICE_ID
• NEXT_PUBLIC_APP_URL
• RESEND_API_KEY
• RESEND_FROM_EMAIL
• CRON_SECRET
• LATEX_SERVICE_URL (optional; defaults to http://localhost:3005/api/compile)

3) Start Supabase locally

npx supabase start
npx supabase db push

Notes:

• Keep DB schema changes in supabase/migrations/ only.
• Do not edit schema directly in Supabase dashboard.

4) Start app services

npm run dev

Optional local PDF service (if needed outside Docker compose):

cd latex-service
npm install
npm run dev

Quality Gates (Before Push)

npx tsc --noEmit
npm run lint
npm run test
npm run build

End-to-End Tests (Playwright)

e2e/public/** covers unauthenticated flows (marketing pages, legal pages, sign-up's legal gate, protected-route redirects, wrong-password sign-in) and needs no extra setup beyond local Supabase running.

e2e/authenticated/** (dashboard, resume CRUD, Stripe checkout) needs a real signed-in session, which requires test-mode Clerk + Stripe credentials — see .env.test.local.example. Copy it to .env.test.local (gitignored) and fill in:

• a Clerk development instance's pk_test_/sk_test_ keys (a separate Clerk app from whatever .env.local points at is safest, but a dev instance is inherently test-safe)
• a Stripe test-mode sk_test_ secret key and test price_... id — never reuse a live Stripe key here, playwright.config.ts refuses to start if it detects _live_ in any of these three keys
• E2E_TEST_USER_EMAIL / E2E_TEST_USER_PASSWORD for a throwaway account e2e/global-setup.ts creates (or reuses) via the Clerk Backend API and seeds directly into the local users table (no webhook forwarder needed locally); e2e/global-teardown.ts deletes it again after the run.

npm run test:e2e        # headless run
npm run test:e2e:ui     # interactive UI mode

The Stripe checkout spec only asserts a real Checkout Session URL comes back — it never completes a purchase. The webhook-driven plan-upgrade lifecycle is covered separately by tests/api/webhooks-stripe.test.ts.

Runtime Endpoints

Healthcheck

• Endpoint: /api/health
• 200 + status=ok: integrations and DB probe are healthy
• 503 + status=degraded: missing critical integration config or failed DB probe

Follow-up Cron

• Endpoint: /api/cron/followup-7d
• Auth:
  • Authorization: Bearer <CRON_SECRET>
  • x-cron-secret: <CRON_SECRET>
• Query params:
  • dryRun=true|false
  • limit=1..500
  • retries=0..3

Examples:

curl -X POST "https://your-domain.com/api/cron/followup-7d?dryRun=true&limit=25" -H "Authorization: Bearer <CRON_SECRET>"
curl -X POST "https://your-domain.com/api/cron/followup-7d?limit=100&retries=1" -H "Authorization: Bearer <CRON_SECRET>"

Stripe Billing

• Checkout: /api/billing/checkout
• Billing portal (manage/cancel subscription): /api/billing/portal
• Webhook: /api/webhooks/stripe
• Requires valid STRIPE_SECRET_KEY (sk_test_... for dev, sk_live_... for prod), STRIPE_PRO_PRICE_ID, STRIPE_WEBHOOK_SECRET
• See .env.prod.example for the full var list and RUNBOOK.md's "Local Stripe Testing" section for stripe listen/stripe trigger usage

Observability Data

• public.webhook_events: idempotency claims for Clerk/Stripe webhook events
• public.email_events: welcome/followup send outcomes and dedup keys (source_event_id)
• public.product_events: product funnel instrumentation (resume_created -> ... -> checkout_started)

Troubleshooting

Stripe checkout returns config error

• Verify STRIPE_SECRET_KEY and STRIPE_PRO_PRICE_ID are set.
• Verify NEXT_PUBLIC_APP_URL points to current environment URL.

Stripe webhook signature errors

• Verify STRIPE_WEBHOOK_SECRET matches webhook endpoint secret.
• Ensure raw request body is forwarded unchanged by proxies.

Clerk webhook sync failures

• Verify CLERK_WEBHOOK_SECRET is configured.
• Replay event and confirm dedup rows in webhook_events.

Clerk error: "Production Keys are only allowed for domain ..."

• Cause: using pk_live/sk_live on localhost.
• Fix for local development:
  • use a Clerk development instance (pk_test_..., sk_test_...) in .env.local
  • keep live keys only in production environments/domains
• Alternative: run the app from an allowed production subdomain with matching origin.

Email sends fail or duplicate

• Check email_events.status, error, and source_event_id.
• Confirm Resend credentials and sender identity are valid.
• Review cron runs in dry-run first when diagnosing follow-up behavior.

AI endpoints blocked by rate limits

• Confirm Upstash env vars are set.
• Free users are limited; upgrade path should show showUpgrade response.

Supabase relation missing errors

• Run pending migrations (npx supabase db push).
• Confirm local stack is running (npx supabase start).

Operational Guide

For deployment, incident response, and rollback procedures, see RUNBOOK.md.