Every finals season I'd end up doing the same algebra on a notes app: "I have a 91% in homework (20%), 84% on the midterm (30%)... what do I need on the final (50%) to get an A-?" So I built GradeHQ to do it for me — and then kept adding to it until it became a real side project.
Live: gradehq.vercel.app
Code: github.com/yashmitb/gradecalc (MIT)
What it does
Add your courses with weighted categories (homework, midterms, final, etc.)
Enter scores as you get them back
Pick a target letter grade and it solves for exactly what you need on whatever's left
Optional AI auto-fill: drop in a syllabus PDF and/or a screenshot (or PDF) of your Canvas grades, and it extracts your categories, weights, and scores for you
Everything is local-first — courses are stored in localStorage, nothing's saved server-side except the file you choose to auto-fill, which is sent once to Gemini and discarded.
Stack
Next.js 16 (App Router, Turbopack)
TypeScript
Tailwind v4
Framer Motion for the animations/transitions
Gemini 2.5 Flash for the auto-fill parsing
No backend database — just one API route (/api/parse) that proxies to Gemini
The auto-fill flow
This was the fun part. The /api/parse route takes the uploaded files (PDF/PNG/JPG, up to 4), sends them to Gemini with a prompt asking it to extract { name, categories: [{ name, weight, score }], flags: [] }.
A few things I had to handle:
Uncertain extractions shouldn't be silently guessed. If Gemini can't confidently read a score or weight, it returns a flags array explaining what it left blank and why. The UI shows these to the user before importing, so they can fill them in themselves instead of getting a wrong number with no explanation.
Shared vs. personal API keys. The app ships with an optional shared/free Gemini key (server-side env var) so most users don't need to do any setup. If that key hits its daily quota, the API returns a server-busy code and the UI lets the user paste their own free key inline to retry — saved only in their browser.
Making a 10-20 second wait feel okay. Gemini calls on multi-page PDFs can take a while. Instead of a static "Loading...", the extract button cycles through short status messages ("Reading files…", "Scanning syllabus…", "Matching scores…", etc.) every ~1.3s, tailored to whether you uploaded a PDF, an image, or both. "Almost done…" only shows up after the cycle has looped through twice — so it doesn't lie to you on a request that just started.
What's next
More grading scale presets (currently a standard A+ through F scale)
Better handling of edge cases in syllabus formats
Probably a dark/light theme toggle since right now it's dark-only
Repo's open source and PRs are welcome — especially around the parsing prompt, since LMS export formats vary a ton between schools. Feedback appreciated!