IPSkill — Developer Hub

Monorepo for the Developer Hub (skill validation layer) described in PLAN.md: candidates connect their GitHub account and get a profile dashboard showing language breakdown, activity, and repo quality signals — one input alongside manual technical screening, not a replacement for it.

Structure

apps/web      Next.js dashboard (App Router, TypeScript, Tailwind, NextAuth)
apps/mobile   Expo/React Native app (TypeScript)
packages/shared  Branding tokens, shared types, GitHub API client

Prerequisites

• Node 20+
• pnpm (corepack enable or npm i -g pnpm)
• Two GitHub OAuth Apps (web and mobile need separate ones — see below)

GitHub OAuth setup

Create both apps at https://github.com/settings/developers:

1. Web app — Authorization callback URL: http://localhost:3000/api/auth/callback/github
2. Mobile app — Authorization callback URL: ipskill:// (GitHub OAuth Apps only support one fixed callback URL each, and the mobile app redirects to a custom ipskill:// scheme instead of a localhost URL, so it can't share the web app's OAuth App.)

Copy the env files and fill in the values:

cp apps/web/.env.example apps/web/.env.local
cp apps/mobile/.env.example apps/mobile/.env

• apps/web/.env.local: GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET (web app), GITHUB_MOBILE_CLIENT_ID/GITHUB_MOBILE_CLIENT_SECRET (mobile app — the secret is only ever used server-side in apps/web's token-exchange route), NEXTAUTH_SECRET (openssl rand -base64 32), NEXTAUTH_URL, SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY (work history storage — see below).
• apps/mobile/.env: EXPO_PUBLIC_GITHUB_CLIENT_ID (the mobile app's client ID only — never the secret), EXPO_PUBLIC_AUTH_BACKEND_URL pointing at the running apps/web instance.

Work history, certifications & skill tests (Supabase)

Unlike Skills/Projects, work history, certifications, and skill test results aren't sourced from GitHub — they need real storage. The ipskill Supabase project holds:

• work_experience (company, role, location, dates, description)
• certifications (name, issuer, issue/expiry dates, credential ID/URL, description)
• skill_test_templates / skill_test_questions / skill_test_attempts — lightweight, in-house multiple-choice tests (3 seeded: JavaScript, Python, SQL fundamentals). This is deliberately not a real code-execution sandbox; the plan (see improvements.md) is to migrate to a proctored third-party vendor (CodeSignal/HackerRank/Coderbyte) once there's revenue to justify it. Correct answers (correct_index) never leave the server — /start only ever returns question text and choices, and scoring happens in /api/skill-tests/attempts/[id]/submit.

All are keyed by the candidate's GitHub numeric ID (stable across username changes, unlike the login string).

There's no Supabase Auth involved — auth is still GitHub OAuth via NextAuth. Both tables have Row Level Security enabled with no policies, so the only way to read or write them is the service-role key, and that key is only ever used server-side (apps/web/src/lib/supabase.ts, guarded by the server-only import). Every /api/experience and /api/certifications route re-derives the candidate's identity from the authenticated NextAuth session before querying — a request can never read or write another candidate's rows by passing a different ID, since the ID isn't taken from the request at all.

Grab SUPABASE_SERVICE_ROLE_KEY from the Supabase dashboard (Project Settings → API → service_role) — it's a secret and isn't obtainable through tooling, by design.

The mobile app can't hold an OAuth client secret, so it exchanges its GitHub authorization code for an access token via apps/web's /api/mobile/github-token route rather than talking to GitHub's token endpoint directly. This means apps/web needs to be running for mobile login to work.

Development

pnpm install
pnpm dev:web      # http://localhost:3000
pnpm dev:mobile   # Expo dev server

Test login (no GitHub OAuth needed)

Set ALLOW_TEST_LOGIN=true in apps/web/.env.local to register an extra "test-account" NextAuth provider and show a "Continue as Test User" button on the login page. It logs straight into a fixture developer profile with realistic GitHub-shaped data (repos, languages, skill fingerprint, commit history) — no real OAuth round trip, no GitHub access token needed — so every GitHub-derived page (Profile, Skills, Projects, Analytics) can be exercised end to end. Supabase-backed features (Experience, Certifications, Verified Skills, the display-name override) still need a real SUPABASE_SERVICE_ROLE_KEY to read/write data, since those aren't mocked.

Never set ALLOW_TEST_LOGIN on a real deployment — it's deliberately not gated by NODE_ENV (Vercel builds preview deployments with NODE_ENV=production too), so leaving it unset is what keeps the bypass from existing at all outside your own machine.

What's real vs. placeholder

• Real: GitHub OAuth login (web + mobile), live GitHub data (repos, languages, PRs, issues, recent commit activity), skill fingerprint derived from that data, and a Recent Activity timeline (commits/PRs/releases across the top 6 most active repos) on the Projects page.
• Also real: Work history (Experience page), Certifications, Skill tests (Verified Skills panel on the Skills page), and a candidate-editable display name (Profile page — overrides GitHub's optional, often-blank name field) — all backed by Supabase, scoped per-candidate via the authenticated session.
• Also real, on the My Analysis (Analytics) page: Overall Score, Skills Strength, Improvement Areas, Career Readiness, and Learning Momentum are computed from the real skill fingerprint and GitHub commit history; the Skill Radar, Skill Category Breakdown, Strengths/Improvement Areas lists, and Growth Trend (weekly commit volume) are all real derived data.
• Placeholder: Profile Views / Search Appearances / Connection Requests on the Analytics page are derived from account signals, not real platform event tracking (GitHub doesn't expose that data, and IPSkill doesn't have its own analytics pipeline yet). Skill Gap Analysis (vs. market demand) and AI Career Recommendations have no data source wired up yet and render as explicitly-labeled "coming soon" tiles rather than invented numbers. Achievements, Settings, Resume upload, and the Home/Search/Messages tabs are still unbuilt stubs.
• Not started: the candidate verification layer and core ATS/CRM from PLAN.md — this repo currently covers the Developer Hub only.