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.
- Recruvo treats the LLM as a brittle extraction layer and wraps it in enough plumbing to keep hiring workflows usable when the model drifts.
- Its real strength is not resume understanding, but the conversion of messy PDFs into structured records that can be stored, queried, and routed safely.
- The repo’s security posture matters because route protection and HttpOnly cookie sessions make the app feel like software, not a demo.
- The fallback parser turns failure into partial success, which is a better product pattern than letting the whole ATS collapse.
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.
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)
| Approach | Failure behavior | Maintenance burden | Fit for messy PDFs |
|---|---|---|---|
| Regex-first parsing | Breaks on layout drift | High | Poor |
| LLM extraction without guardrails | Breaks when output is malformed | Medium | Good until it fails |
| Recruvo hybrid path | Returns partial structured data | Moderate | Strong |
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.
| Model | Role | Why it matters |
|---|---|---|
| User | Represents candidates, recruiters, and admins | Provides the identity layer for RBAC |
| Resume | Stores file URL plus parsed fields | Connects raw PDFs to structured profile data |
| Application | Links a candidate to a job with status | Turns 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
| Pattern | What it optimizes | What it gives up |
|---|---|---|
| Regex-first parsing | Deterministic rules | Coverage across messy resume layouts |
| Manual recruiter review | Human judgment | Speed and consistency |
| Brittle AI demo | Impressive output when it works | Recovery when it does not |
| Recruvo hybrid flow | Useful structured data plus fallback | Some 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.





