ScholarSearch AI

An AI-powered headhunting and recruitment management platform for universities and tertiary institutions — a portfolio demonstration built by Dr. Barbara Z. Franks for the fictional Caribbean National University.

This is a portfolio demonstration, not a live production hiring system. All candidates, prospects, positions, and records are fictional and generated for demonstration purposes only.

Project Overview

ScholarSearch AI manages the full academic recruitment lifecycle — from workforce planning and position creation through candidate sourcing, eligibility screening, search committee review, interviews, teaching demonstrations, research seminars, finalist comparison, and the department chair's final recommendation — ending in a formal handoff to Human Resources.

AI assists with drafting, summarization, comparison, and workflow automation throughout. AI does not make employment decisions. Every stage that changes a candidate's status requires explicit human review and approval, and the platform is built around that principle end to end (see /app/governance).

The build follows the featured demo search — Associate Professor of Educational Leadership (Faculty of Education, Department of Leadership, Policy and Administration) — from 18 applicants through a completed HR handoff, so the entire workflow can be demonstrated in one continuous narrative.

Technology Stack

• Next.js 16 (App Router) + TypeScript + React 19
• Tailwind CSS v4 with a custom institutional design system (navy, royal blue, warm gold, slate)
• Hand-built shadcn/ui-style component library on Radix UI primitives
• Lucide icons, Recharts for analytics, Framer Motion for the landing page
• React Hook Form + Zod for the position creation wizard
• Zustand (with persist) for client-side demo state — role, drafts, checklists, saved items
• jsPDF for downloadable candidate dossiers
• A provider-agnostic AI service abstraction (src/lib/ai/) — ships with a deterministic mock provider; a production deployment swaps in a Claude/OpenAI-backed implementation of the same interface with no component changes
• Architected to move to Supabase for persistence (see .env.example and "Mock Data & Architecture" below)

Installation

npm install
npm run dev

Open http://localhost:3000. No environment variables or API keys are required — see .env.example for what a future live-AI/Supabase deployment would need.

Demo Access

There is no real authentication. Use the role switcher in the top bar (or visit /candidate/dashboard directly) to preview the platform as any of the ten roles below. The emails below are illustrative "demo accounts," not functioning logins:

Role	Demo Email
Recruitment Administrator	admin@scholarsearch.demo
Recruiter	recruiter@scholarsearch.demo
Department Chair	chair@scholarsearch.demo
Dean	dean@... (see Users & Roles in-app)
Search Committee Chair	committee.chair@scholarsearch.demo
Search Committee Member	committee@scholarsearch.demo
Executive Approver	executive@...
HR Handoff Officer	hr@...
Candidate	candidate@scholarsearch.demo
Platform Administrator	platformadmin@...

Suggested walkthrough: Land on / → Launch Interactive Demo → Executive Dashboard → open the Associate Professor of Educational Leadership position → Candidates tab → open a finalist's profile (AI Insights tab) → Decisions → Candidate Comparisons → Decisions → Chair Recommendations → Decisions → HR Handoffs. Then switch role to Candidate to see the same search from the applicant's side.

Main Workflows

1. Position Creation — /app/positions/new, a 6-step wizard (Overview → Role Expectations → Qualifications → Competencies → Timeline → Review) with AI-assisted drafting and a live preview.
2. AI Job Description Generator — /app/positions/ads, with tone controls, refinement actions (shorten, more inclusive, more competitive, research/teaching emphasis), version history, and an inclusive-language review panel.
3. Talent Sourcing — /app/talent/sourcing, a simulated headhunting workspace with filterable prospect cards, AI match analysis, AI outreach generation, and side-by-side prospect comparison.
4. Eligibility Screening — /app/applications/eligibility/[id], a 10-category criterion review with an AI-prefilled recommendation that a recruiter must explicitly approve, plus a full decision audit log.
5. AI Candidate Matching — /app/ai-tools/candidate-matching, an adjustable-weight, radar-chart, fully explainable match score (no protected characteristics, ever).
6. Committees & Rubrics — /app/committees, readiness dashboards, and /app/committees/rubrics, where each evaluator scores independently before group results unlock.
7. Interviews & Assessments — preliminary interviews (with an AI question generator), teaching demonstrations, and research seminars (with an AI feedback summary).
8. Candidate Comparison — /app/decisions/comparisons, side-by-side table + radar chart + AI-generated synthesis for 2–4 finalists.
9. Chair Recommendation → Final Dossier → HR Handoff — /app/decisions/*, ending in a downloadable PDF dossier and an interactive HR handoff checklist that surfaces the required "Recruitment phase complete" confirmation once every item is checked.
10. Candidate Portal — /candidate/*, a fully separate applicant-facing experience (dashboard, applications, search, documents, interviews, messages, profile, settings).

AI Features (all simulated for the demo)

Every AI feature is implemented against a single AIService interface (src/lib/ai/types.ts) with a deterministic mockAIService implementation (src/lib/ai/mock-ai-service.ts) — realistic, template-composed output with an artificial delay so loading states are demonstrable, and no network calls or API key required:

• Job description generation + inclusive language review
• Candidate match scoring with a plain-language explanation
• Interview question generation (8 competency categories)
• Outreach email generation
• Candidate / committee-feedback / chair-briefing / HR-handoff summarization
• Finalist comparison synthesis
• A floating AI Recruitment Assistant chat (/app/ai-tools and the global FAB) with keyword-routed suggested-prompt responses

Every AI output in the UI is labeled "AI-generated" and paired with a disclaimer that it supports — but does not replace — human review. See /app/governance for the full policy and /app/governance/activity-log for the simulated audit trail of every AI-assisted action.

Mock Data & Architecture

All data lives in src/lib/data/ and is generated deterministically (seeded PRNG in src/lib/data/rng.ts) so server-rendered HTML and client hydration always match — there is no Math.random() anywhere in the data layer.

• positions.ts — 16 positions (12 active + 4 completed) across 5 faculties / 14 departments
• featured-search.ts — the hand-authored 18-applicant Associate Professor of Educational Leadership search (10 eligible → 6 longlisted → 4 shortlisted → 3 finalists → 1 chair-recommended → 1 completed HR handoff)
• generators.ts + seed.ts — ~70 total candidates, 26 prospects, 8 search committees, 6 outreach campaigns, teaching demonstrations, research seminars, chair recommendations, HR handoffs, notifications, and a full audit/AI-activity log
• src/lib/store.ts — a Zustand store (persisted to localStorage) layers session edits (stage changes, eligibility approvals, rubric submissions, HR checklist state, saved positions, chair decisions, etc.) on top of the read-only seed data, so the demo feels persistent across a session without a backend

Mock vs. production-ready: the UI, routing, component library, validation, and state management are production-quality patterns. What's mocked for the portfolio: the AI provider (swap src/lib/ai/index.ts), authentication/RBAC enforcement (currently a client-side role switcher, not a real auth boundary), and persistence (Zustand + localStorage stands in for Supabase).

Governance Principles

• AI assists with drafting, summarization, comparison, and workflow automation — it never makes a final employment decision.
• Every eligibility call, evaluation, interview outcome, chair recommendation, and HR handoff requires an identified human reviewer.
• Explicitly prohibited: automatic rejection without human review, facial analysis, emotion recognition, personality inference, protected-characteristic inference, disability/political/religious inference, and opaque scoring.
• Full policy, an AI activity log, and role-based access notes live at /app/governance.

Deployment (Vercel)

npm run build

1. Push this repository to GitHub.
2. Import it in Vercel — framework preset Next.js, no environment variables required for the demo build.
3. Deploy. No database or external services are needed for the current (Phase 1) build.

Supabase Migration (future)

No Supabase project or migrations are required today. When wiring up real persistence, the intended shape is one table per exported type in src/lib/data/types.ts (positions, candidates, prospects, search_committees, interviews, teaching_demos, research_seminars, chair_recommendations, hr_handoffs, notifications, audit_log, ai_activity_log, …), with the selector functions in src/lib/data/index.ts swapped from array lookups to Supabase queries — component code does not change.

Roadmap

See /roadmap in the running app for the full four-phase plan (Phase 1 = this build; Phase 2 = Entra ID/Outlook/Teams + live AI; Phase 3 = ORCID/research integrations + talent intelligence; Phase 4 = HRIS/offer/onboarding integration).

Completed Features

Executive dashboard · position wizard + approvals + recruitment plans + AI job ads · candidate directory + talent sourcing + outreach campaigns + talent pools · applications management + eligibility screening + AI review queue + missing documents · candidate profile (8 tabs incl. AI Insights) · CV Intelligence · AI Candidate Matching · search committees + assignments + disclosures + evaluation rubrics + meetings · interview schedule + preliminary/teaching/research/chair interviews + feedback · candidate comparisons · chair recommendations · final dossiers with PDF export · HR handoffs with interactive checklist · AI Recruitment Assistant (hub + floating panel) · recruitment analytics with CSV export · AI governance + activity log · administration (faculties, users, templates, competencies, notifications, audit logs, settings) · full candidate portal · public landing page + roadmap page.

Recommended Next Development Phase

Per the roadmap, Phase 2 (enterprise integration — SSO, calendar/Teams scheduling, a live Claude-backed AIService implementation, and real document parsing) is the natural next step once this demo is validated with stakeholders.

---

Built as part of Dr. Barbara Z. Franks' Curriculum Innovation & Instructional Design Portfolio.