← All projects

2025

AppScreen

An AI job screening platform that grades applicants requirement by requirement and explains every score. It took second place in the professional category at HACC 2025.

Event
Hawaii Annual Code Challenge (HACC) 2025
Award
Second place, professional category
Role
Solo lead
Stack
React, TypeScript, FastAPI, PostgreSQL, Pydantic AI
  • React
  • TypeScript
  • FastAPI
  • PostgreSQL
  • SQLModel
  • Pydantic AI
  • LLM Screening
  • HACC 2025
AppScreen title next to screenshots of an application summary and the requirement-by-requirement candidate match results

Overview

AppScreen is a job application screening platform I built for the Hawaii Annual Code Challenge (HACC) 2025, where it won second place in the professional category. I led the project. Our team was named DarkMode, which is why the repository has that name.

Reading every resume against a long list of job requirements is slow, and two reviewers can read the same resume differently. An AI that hands back one number is faster, but it’s hard to trust: nobody can see why one candidate got a 74 and another a 61.

So AppScreen doesn’t ask the model for a score. It asks for a judgment on each requirement, with a reason, and computes the score from those judgments in plain code. A reviewer can read every judgment, and change any of them.

The application details page: status Under review, the applicant’s name and email, a screening score of 74.04 with the time it ran, and the Staff Platform Engineer job it was submitted to An application under review. The job and applicant are demo data.

Three roles

Every account is a company or an applicant, and admins sit above both. The API checks the role on every request, not just the interface.

  • Companies post jobs, screen the applications they receive, and move candidates through the hiring stages.
  • Applicants upload resumes, search and apply to jobs, and track where each application stands.
  • Admins manage user accounts and can see every listing, application, and screen.

Posting a job

A company can type a listing by hand, or click Fill in with AI and paste a job description or upload one. The job agent reads it and returns a structured listing: title, company, location, job type, remote or not, salary range, closing date, and two lists of requirements, minimum and preferred.

The result fills in the form; it doesn’t save anything. The company checks it, edits any line, drags requirements into order, and then posts it. Every field the model returns is optional, so a description with no salary just leaves that field empty instead of failing.

Applying

Applicants upload resumes as PDF, Word (.docx), or plain text files. The server pulls the text out once, at upload, and stores it with the file. To apply, the applicant picks a job, chooses one of their resumes, and can add a cover letter. The database allows one application per person per listing.

Reviewing

For a company, the Applications page is the review queue. Applications are grouped by stage (submitted, under review, interview, accepted, rejected, withdrawn), and within each stage the highest match score comes first. Cards under review or at the interview stage have buttons to advance or reject the candidate.

Opening an application shows the summary above, the job, the resume text, the cover letter, and a Run screen button.

How screening works

How AppScreen screens an applicationOn the company side, a pasted or uploaded job description goes to the job agent, an LLM call that fills in the listing form, and the company saves a job listing with minimum and preferred requirements. On the applicant side, an uploaded PDF, DOCX, or text resume goes through a text parser and is stored with its extracted text. The requirements and the resume text both go to the screen agent, an LLM call that returns a label and a reason for each requirement. Plain code turns the labels into a weighted score, and the review queue sorts applications by that score. When the company edits a label, the score is recalculated by the same code.COMPANYAPPLICANTRequirementsResume textLabel + reason for each requirementMatch %Company editsa label, scoreis recalculatedJob descriptionPasted text or a fileJob agentLLM · fills the listing formJob listingMinimum + preferred listsResume uploadPDF · DOCX · TXTText parserpypdf · python-docxStored resumeFile + extracted textScreen agentLLM · a label and reason eachScoringPlain code · weighted pointsReview queueBy stage, highest score firstLLM call (Pydantic AI, OpenAI)Plain code or stored dataHuman override

1. Resume to text

Uploads go through a small parser registry. Each parser is a class registered for its file extensions and MIME types: pypdf for PDF, python-docx for Word, and a decoder for plain text. Supporting a new format means adding one class. The same parsers also read job descriptions that companies upload.

2. One judgment per requirement

When a company runs a screen, the screen agent gets the job title, description, both requirement lists, and the resume text. It doesn’t get the applicant’s account details. It returns one result for each requirement, in the same order: a label and a short reason.

There are four labels: highly qualified, qualified, meets expectations, and not qualified. Both agents use Pydantic AI with typed output schemas, so a response that doesn’t fit the schema is rejected instead of half-parsed.

The minimum qualifications table: each requirement on the left, and on the right a colored label such as Highly qualified or Meets expectations with a one-sentence reason drawn from the resume Each requirement gets its own label and reason. In the two “Meets expectations” rows, the resume implies the skill but doesn’t name the tools.

3. The score is arithmetic

The model never produces a number. Code turns each label into points, and minimum requirements count twice as much as preferred ones:

Label Points Minimum (×2) Preferred (×1)
Highly qualified 4 8 4
Qualified 3 6 3
Meets expectations 2 4 2
Not qualified 0 0 0

The match score is the points earned divided by the points possible, as a percentage. For example, a listing with two minimum requirements and one preferred one has 20 possible points. A candidate rated highly qualified and meets expectations on the minimums, and not qualified on the preferred one, earns 8 + 4 + 0 = 12, for a score of 60.

The same labels always give the same score, and anyone can trace it back. A missed requirement doesn’t reject anyone on its own. It costs points and shows up in the table, and the decision stays with the reviewer.

4. A person has the last word

A company reviewer can click Edit applicant results to change any label or rewrite any reason. Every requirement needs a label before it saves, and the server recalculates the score with the same code. Only the company that owns the listing, or an admin, can do this.

Each application is screened once. Running it again returns the stored result, so a score doesn’t shift between page loads and the model isn’t called twice. Screening also moves the application to under review.

Engineering decisions

  • Template first, domain on top. I started from the official full-stack FastAPI template for login, JWT auth, user management, migrations, and Docker Compose, removed its example code, and built the hiring features as separate services: files, parsers, resumes, jobs, applications, and screens. Each has its own models, routes, and a service class that FastAPI injects.
  • Permissions live in the services. Companies only see applications to their own listings, applicants only see their own, and an applicant can only attach a resume they uploaded. These checks run on the server for every request.
  • Hiring stages are a state machine. Submitted can go to under review or rejected, under review to interview or rejected, and interview to accepted or rejected. Accepted, rejected, and withdrawn are final. Only the owning company can move an application forward, and only the applicant can withdraw it. Admins can do both.
  • Storage behind an interface. Files go through a storage interface with a local disk version, so a cloud store can replace it without touching the resume code. If saving a resume’s database record fails, the stored file is deleted.
  • Types from end to end. The frontend’s API client is generated from the backend’s OpenAPI spec, so a changed model shows up as a TypeScript error instead of a runtime bug.
Area Technology Details
Frontend React, TypeScript, Vite, Chakra UI TanStack Router and Query, React Hook Form
API client openapi-ts Generated from the FastAPI OpenAPI spec
Backend FastAPI, SQLModel One service per domain area
Database PostgreSQL, Alembic JSON columns for requirement lists and screening results
AI Pydantic AI, OpenAI Two agents with typed outputs; the model is a setting
Parsing pypdf, python-docx PDF, Word, and plain text
Auth JWT Company and applicant roles, plus admins
Deployment Docker Compose From the FastAPI template

What I learned

  • Let the model judge and let code count. Keeping the model to one label per requirement made the score repeatable, easy to explain, and easy for a person to correct.
  • Show the reason next to the result. The one-line reasons did more for trust than the score did. A reviewer can disagree with a specific line instead of the whole verdict.
  • Match results by key, not by position. The model is told to answer in the same order as the requirements, and the page pairs them by position. Next time I’d have it repeat each requirement or check the count on the server, so a skipped line can’t shift the rest.