clinician-faculty-match

Clinician–Faculty Match (MVP)

A full-stack application that intakes clinician research problems and matches them with relevant faculty using hybrid keyword + semantic (pgvector) similarity.

See SETUP.md for installation and local development instructions.

How It Works

1. Clinicians submit research problems describing what they need help with
2. The matching engine scores faculty against submissions using keyword/domain overlap and vector cosine similarity
3. Admins/Reviewers triage matches, track interactions, and manage the pipeline from submission through to collaboration

Tech Stack

• Framework: Next.js 14 (App Router), TypeScript, Tailwind CSS
• Database: PostgreSQL 15 + pgvector for vector similarity search
• ORM: Prisma 5
• Auth: NextAuth (JWT, Credentials provider for dev)
• Forms: React Hook Form + Zod validation
• Data fetching: TanStack React Query
• Testing: Vitest + React Testing Library

Project Structure

src/
├── app/                    # Next.js App Router pages and API routes
│   ├── api/                #   REST endpoints (auth, submissions, faculty, matching, embeddings)
│   ├── auth/               #   Sign-in, account creation, invite redemption
│   ├── dashboard/          #   Admin dashboard
│   ├── faculty/            #   Faculty directory and profile pages
│   ├── forum/              #   Grant/collaboration forum
│   ├── submissions/        #   Submission intake and management
│   └── (marketing)/        #   Landing page
├── components/             # React components
│   ├── ui/                 #   Base UI primitives (Card, Input, Modal, etc.)
│   ├── faculty/            #   Faculty profile form
│   ├── dashboard/          #   Dashboard widgets
│   ├── forum/              #   Forum components
│   └── actions/            #   Action buttons and selects
├── lib/                    # Shared utilities (Prisma client, matching logic, helpers)
├── types/                  # TypeScript types and NextAuth config
└── styles/                 # Global CSS

prisma/
├── schema.prisma           # Database schema (13 models)
├── migrations/             # SQL migration files
└── seed.ts                 # Seed script with example data

scripts/
└── run.sh                  # One-command setup and run script

Data Model

Model	Purpose
User	Accounts with roles: CLINICIAN, FACULTY, ADMIN, REVIEWER
FacultyProfile	Faculty details — keywords, methods, domains, equipment, embedding
Publication	Faculty publications with vector embeddings
Grant	Faculty grants with vector embeddings
Submission	Clinician research problems with vector embeddings
Match	Links a submission to a faculty member with a similarity score
Interaction	Event log for contacts, meetings, notes, status changes
Taxonomy	Hierarchical terms (MeSH, internal)
EmbeddingMetadata	Tracks embedding provider, model, and dimensions

Embeddings are stored as vector(1536) columns with IVFFLAT indexes for fast cosine similarity search.

Authentication (Dev Mode)

Auth is passwordless and dev-friendly:

• Go to /auth/signin and enter any email
• Unknown emails are auto-provisioned as CLINICIAN
• Change roles via Prisma Studio (pnpm prisma:studio)

Seeded accounts (after pnpm prisma:seed):

• admin@example.edu — ADMIN
• clinician@example.edu — CLINICIAN

Scripts

pnpm dev               # Next.js dev server
pnpm build             # Production build
pnpm start             # Start production server
pnpm lint              # ESLint
pnpm test              # Vitest
pnpm prisma:generate   # Generate Prisma client
pnpm prisma:migrate    # Run migrations (dev)
pnpm prisma:studio     # Prisma Studio GUI
pnpm prisma:seed       # Seed database