PlacementOS

PlacementOS is an explainable placement-readiness and job-tracking application for students. It compares evidence-backed skills with requirements from official job sources, recommends roles at or above 50% required-skill coverage, explains missing skills, and keeps a private application history.

What is included

• Google OAuth through Supabase Auth using the authorization-code flow.
• Postgres persistence for profiles, skills, jobs, saves, applications, event history, and resume metadata.
• Row-level security (RLS) on every user-owned table.
• Private Supabase Storage bucket for PDF/DOCX resumes up to 5 MB.
• Soft deletion for skills, saved roles, and resumes.
• Append-only application status events.
• Official Greenhouse and Lever job-board ingestion with fixed hosts, timeouts, source attribution, and a protected daily cron route.
• Deterministic requirement extraction and recommendation logic; no unexplained hiring prediction.
• Responsive public site, secure dashboard, onboarding tutorial, profile/evidence editor, job discovery, application tracking, resume vault, privacy explanation, and legal pages.

PlacementOS intentionally does not scrape LinkedIn or bypass protected pages. A LinkedIn URL may be stored as a source link only when it is provided through an allowed integration or manual entry.

Local setup

1. Create a Supabase project.
2. Copy .env.example to .env.local and fill in the values.
3. Run supabase/migrations/202607140001_secure_placementos.sql in the Supabase SQL editor or through the Supabase CLI.
4. In Supabase Auth, enable Google and add these redirect URLs:
   • http://localhost:3000/auth/callback
   • https://placementos-one.vercel.app/auth/callback
5. Add the same environment variables to Vercel.
6. Configure job sources in GREENHOUSE_BOARDS and LEVER_SITES using company:token entries.
7. Run:

npm install
npm test
npm run lint
npm run build
npm run dev

Never commit .env.local, the Supabase secret/service-role key, Google client secret, or cron secret. The official Vercel Marketplace integration supplies NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, and SUPABASE_SECRET_KEY automatically.

How the recommendation model works

extractRequirements() maps terms in a plain-text official description to a canonical skills vocabulary. It marks “preferred”, “bonus”, “plus”, and similar nearby language as preferred rather than required.

matchJob() then classifies every requirement:

• Strong: confirmed skill, intermediate/advanced level, and evidence.
• Partial: skill is present but beginner-level or lacks evidence.
• Missing: skill is not in the confirmed profile.

Required-skill coverage is the percentage of required skills that are present (strong or partial). A role is recommended for review when coverage is at least 50%. The overall readiness score separately weights required alignment (65%), preferred alignment (20%), and evidence coverage (15%). It never predicts selection or hiring.

File guide

Product interface

• app/page.tsx — public landing page and production-setup state.
• app/dashboard/page.tsx — protected server entry point.
• app/dashboard/dashboard-client.tsx — onboarding, overview, discovery, profile, applications, resume vault, and privacy views.
• app/globals.css — visual system, responsive layouts, accessible focus states, reduced-motion behavior, loading, empty, and error states.
• components/google-login.tsx — Google OAuth initiation.
• app/privacy/page.tsx and app/terms/page.tsx — user-facing data and model limitations.

Authentication and data

• lib/supabase/client.ts — browser Supabase client.
• lib/supabase/server.ts — cookie-aware server client.
• lib/supabase/admin.ts — server-only service client used only by trusted ingestion.
• proxy.ts — session refresh and dashboard route protection.
• app/auth/callback/route.ts — exchanges the OAuth code for a session.
• supabase/migrations/202607140001_secure_placementos.sql — tables, constraints, indexes, storage bucket, triggers, grants, and RLS policies.
• app/api/workspace/route.ts — authenticated profile, skill, save, application, and timeline operations with Zod validation.
• app/api/resumes/route.ts — validated private upload and deletion.

Jobs and matching

• app/placement-data.ts — canonical skills, deterministic extraction, scoring, threshold logic, and shared types.
• lib/jobs/sources.ts — Greenhouse and Lever adapters; HTML is converted to plain text and requests use a fixed host and timeout.
• app/api/jobs/sync/route.ts — cron-secret-protected database upsert.
• vercel.json — daily ingestion schedule and security response headers.

Verification

• tests/placement-engine.test.ts — extraction and scoring behavior.
• tests/recommendation-model.test.ts — exact 50% threshold, below-threshold behavior, missing-skill output, and deterministic IDs.
• tests/security-contract.test.ts — RLS, absence of browser persistence, authenticated ingestion, and fixed official sources.
• tests/rendered-html.test.mjs — production-render contract for the public and legal pages.

Suggested learning path

1. Start with app/placement-data.ts to understand pure functions and explainable scoring.
2. Read supabase/migrations/202607140001_secure_placementos.sql to learn relational modelling, constraints, RLS, triggers, and storage policies.
3. Follow a profile update from dashboard-client.tsx to app/api/workspace/route.ts, then to the RLS policy.
4. Follow Google login from google-login.tsx through app/auth/callback/route.ts and proxy.ts.
5. Study lib/jobs/sources.ts and the sync route to learn safe external API ingestion.
6. Run the tests and change one threshold or alias to see how the expected behavior responds.

Security operations

Application controls reduce risk but cannot guarantee zero data loss. Enable the backup and point-in-time recovery features appropriate to your Supabase plan, test restoration, rotate secrets, review OAuth redirect URLs, and monitor job-sync and authentication errors. Keep the service-role key server-only.