Role Fit

Role Fit

AI understands. Role Fit measures. Humans decide.

Role Fit is an evidence-based career and recruitment intelligence platform. It connects what employers require with what candidates can actually demonstrate — using local/open-weight AI to extract structured facts, deterministic code to measure fit, and a human to make every hiring decision.

• Career Intelligence — see the real requirements, experience expectations, and skill gaps for a target role.
• Recruitment Intelligence — screen candidates against a job description with cited evidence and explainable scores.

Role Fit is intentionally not a chatbot, not a resume builder, and not a black-box hiring oracle.

Why it exists

Candidates often prepare against generic advice instead of the requirements employers actually repeat. Recruiters spend hours re-reading resumes and struggle to explain why one candidate ranks above another.

Role Fit turns that unstructured information into a shared, inspectable model:

Job description / PDF · DOCX · TXT · MD
        │
        ▼
Server text extraction                 /api/ingest · unpdf · mammoth
        │  per-file failures and limits
        ▼
AI extraction (mock | ollama)          unstructured → typed JSON
        │  validated at the boundary (lib/ai/schemas.ts)
        ▼
Skill normalization                    aliases → canonical skills
        │
        ├──────────────► Market / evidence grounding (sample data today)
        ▼
Deterministic matching                 requirement → cited evidence
        │
        ▼
Deterministic scoring                  50 / 25 / 15 / 10 weights
        │
        ▼
Deterministic routing                  Strong Match · Review · Needs Verification
        │
        ▼
Human review                          decision + notes persisted

Every matched requirement carries evidence. No candidate is ever automatically rejected.

Status: working demo, not a production pipeline

The product thesis is fully implemented end to end, but the screening path still uses demo data. Be precise about what works today:

Concretely: uploaded files go to /api/ingest, where PDF/DOCX/TXT/MD text is extracted and invalid files are reported individually. The wizard then screens each candidate through the validated offline extractor and the deterministic engine. Sample mode skips the upload and uses fictional fixtures, and the resulting screening is labelled Sample. Files are parsed per run and not stored. Candidate/provider extraction still runs in the browser, so the implemented Ollama provider is not yet wired through a server route. Screenings and decisions live in localStorage. Market data comes from lib/data/sample-data.ts and is always labelled Sample.

Closing these gaps is the job of [docs/ROADMAP.md](./docs/ROADMAP.md).

Stack

No proprietary cloud LLM is used or supported. Providers extract facts; they never return a score.

Quick start

# 1. Install dependencies (Node 22)
nvm use
npm install

# 2. Configure environment
cp .env.example .env

# 3. Generate the Prisma client and prepare the local database
npm run db:generate
npm run db:push
npm run db:seed          # optional: seeds an organization + demo user

# 4. Run the app
npm run dev              # http://localhost:3000

The app runs without a database today — Prisma is not yet on the request path — but db:generate is required before typechecking or seeding because prisma/generated/ is git-ignored.

Environment

DATABASE_URL="file:./prisma/dev.db"   # resolved from the project root
AI_PROVIDER="mock"                    # "mock" | "ollama"
OLLAMA_BASE_URL="http://localhost:11434"
OLLAMA_MODEL="llama3.2"
NEXT_PUBLIC_APP_NAME="Role Fit"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

To use a local model, start Ollama and set AI_PROVIDER="ollama". Extraction currently runs in the client; real deployments should move it behind a server route (see roadmap Phase 1.4) so Ollama does not need CORS.

Commands

CI (.github/workflows/ci.yml) runs npm ci, db:generate, verify, and build on every push and pull request to main.

Routes

How scoring works

Required skills 50 · Experience 25 · Preferred skills 15 · Evidence quality 10 = 100.

required   = round(50 × matchedRequired / totalRequired)
experience = min(25, round(25 × min(candidateYears / requiredYears, 1.25)))
preferred  = round(15 × matchedPreferred / totalPreferred)
evidence   = min(10, 4·hasExperience + 3·hasProjects + 2·hasEducation + 1·hasCertifications)
total      = min(100, required + experience + preferred + evidence)

Routing:

Strong Match        : total >= 85 AND missingRequired == 0 AND candidateYears >= requiredYears
Review              : total >= 60 OR missingRequired <= 2
Needs Verification  : otherwise

The engine is deterministic: same candidate, requirements, and weights → same score. The golden test anchor is 76 / Review and must not drift without a documented product decision.

Full specification: [docs/ENGINE.md](./docs/ENGINE.md).

Project structure

app/                    App Router pages (marketing + dashboard shell)
components/             UI primitives, layout shell, recruitment/career views
lib/
  ai/                   Provider interface, schemas, mock + Ollama providers, prompts
  matching/             Requirement ↔ candidate evidence evaluation
  scoring/              Deterministic weighted scoring
  routing/              Queue classification (no auto-reject)
  normalization/        Skill taxonomy + alias matching
  retrieval/            Market grounding (static today)
  batch/                Per-candidate extraction → match → score → route
  pipeline/             Extraction + grounding coordinator
  store/                Shared localStorage-backed client store
  tests/                Deterministic engine assertions
  data/                 Sample market/screening fixtures
types/                  Presentation/domain types used by the UI
prisma/                 Schema, seed, generated client (git-ignored)
docs/                   Architecture, engine, data model, roadmap

There are currently two type systems — AI contracts in lib/ai/schemas.ts and presentation types in types/index.ts. Unifying them is Phase 1 of the roadmap; do not add a third shape in the meantime.

Documentation

Contributors and AI agents should read AGENTS.md before changing code.

Principles

1. AI never computes a score or makes a hiring decision. It only extracts typed facts.
2. Every match cites evidence. No invented citations.
3. No automatic rejection. Routing informs; a human decides.
4. Deterministic in, deterministic out. No randomness, clock dependence, or model calls in scoring.
5. Validate at every boundary. Untrusted provider output is checked before it enters the engine.
6. Local/open-weight AI only. No proprietary cloud LLM dependency.
7. Never present sample data as live market data. Sample labels stay visible.
8. Human decisions are persisted state, not UI decoration.