resume-screening-portal: How Recruvo Turns PDFs Into Structured Hiring Data Without Trusting the Model Too Much

A FastAPI, React, and Supabase ATS that uses LLM extraction, JSON-only prompts, HttpOnly cookies, and fallback parsing to stay useful when the AI layer misbehaves.

8 min read • View on GitHub • More from harshal-codes

A wide editorial scene of a recruiter’s desk where messy PDF resumes feed into a narrow machine on the left and clean candidate cards emerge on the right. A small valve labeled LLM sits between the two, with a visible fallback lever beside it, explaining that the system is built to control uncertainty rather than pretend it does not exist.
Recruvo’s real idea is not AI screening. It is AI screening with enough structure around it to survive bad inputs, bad outputs, and partial failures.
Key Takeaways

Most ATS projects promise intelligence and deliver a form. resume-screening-portal takes a sharper route: it treats resume parsing as a structured data problem, not a language problem. The model matters, but the production glue matters more.

The core trick: resume parsing without hand-written extraction rules

The pipeline starts with a plain PDF. `resume_parser.py` uses pdfplumber to pull text out of each page, then hands that text to `llm_parser.py`, which asks an LLM for JSON that can be stored directly in the database. That move replaces a brittle pile of regexes with a single prompt contract.

The interesting move is not extraction alone. It is extraction plus containment, so the app still has something useful to do when the model gets chatty or wrong.

A close-up cross-section of a pipeline with three chambers: raw PDF text, JSON-only LLM output, and structured database rows. One cracked branch diverts to a side chute labeled fallback keyword extraction, which still feeds a smaller usable data table.
This is the repo’s most practical idea: the AI path is preferred, but the app keeps a recovery lane open so the product can still move forward.

Why the pipeline is built to fail safely

The backend does not assume the model will behave. `llm_parser.py` strips wrapper text such as fenced code blocks, then tries to normalize the response into something parseable. In `resumes.py`, the fallback path keeps the interface alive with a keyword-based skill pass when the LLM or network call fails.

content = content.replace("```json", "").replace("```", "")
json_data = json.loads(content)

if not parsed_resume.get("skills"):
    parsed_resume["skills"] = extract_keywords(raw_text)
ApproachFailure behaviorMaintenance burdenFit for messy PDFs
Regex-first parsingBreaks on layout driftHighPoor
LLM extraction without guardrailsBreaks when output is malformedMediumGood until it fails
Recruvo hybrid pathReturns partial structured dataModerateStrong

That is the important production move. A lot of AI demos are binary: either the model works or the app stops making sense. This repo accepts partial truth, then keeps moving.

Security is not an afterthought here

Auth is built like an actual application concern, not a UI flourish. The `require_roles(*roles)` dependency protects routes by role, and session state is kept in HttpOnly cookies instead of exposed browser storage. That choice narrows the blast radius of XSS and makes the backend responsible for access control, where it belongs.

current_user: User = Depends(require_roles("recruiter"))
response.set_cookie("access_token", token, httponly=True, secure=True, samesite="Lax")

The data model connects candidates, jobs, and parsed resumes

The schema is what turns extraction into a product. `User`, `Resume`, and `Application` create a bridge between raw uploads and lifecycle state, so the system can store a file, attach structured fields, and track where a candidate sits in the process. Supabase provides both the PostgreSQL layer and file storage, which keeps the stack narrow and legible.

ModelRoleWhy it matters
UserRepresents candidates, recruiters, and adminsProvides the identity layer for RBAC
ResumeStores file URL plus parsed fieldsConnects raw PDFs to structured profile data
ApplicationLinks a candidate to a job with statusTurns parsing into a hiring workflow

The frontend is mostly a traffic controller

The React app does not try to be clever. `AuthContext.jsx` owns session state, and `RootRedirect` in `App.jsx` reads the JWT payload to send people to the right dashboard immediately after login. That makes the UI feel responsive without burying business logic in the browser.

if (role === 'admin') navigate('/admin');
else if (role === 'recruiter') navigate('/recruiter');
else navigate('/candidate');

What this project gets right compared with older ATS patterns

PatternWhat it optimizesWhat it gives up
Regex-first parsingDeterministic rulesCoverage across messy resume layouts
Manual recruiter reviewHuman judgmentSpeed and consistency
Brittle AI demoImpressive output when it worksRecovery when it does not
Recruvo hybrid flowUseful structured data plus fallbackSome model dependence, but contained

The article’s honest read is simple: this is still a prototype, but it is a disciplined one. There are no visible tests in the tree, and the system depends on external services like OpenRouter and Supabase. Even so, the architecture shows good instincts: reduce surprise, keep outputs structured, and make failure less dramatic.

Sources