GradeLens

GradeLens - Rubric Based AI Powered Smart Evaluation System

Comment

Inspiration

Grading written work is slow, and students often get a bare mark with little explanation. Teachers have rubrics, but applying them consistently across dozens of scripts is tiring, and fully automated AI grading isn't trustworthy enough to hand students a score unchecked. We wanted a tool that saves teachers time without taking the final decision away from them: AI drafts, the teacher decides.

What it does

GradeLens is a rubric-based evaluation platform with two roles.

  • Teachers create classes with join codes and build assignments with MCQ, short-answer and written questions. Each written question carries its own rubric and sample answer.
  • Students enroll with a join code and submit typed answers or a PDF, subject to server-enforced deadlines and one submission per assignment.
  • Grading: MCQs are auto-graded. Written answers are drafted by a Groq-hosted LLM against the teacher's rubric, producing a score, feedback, strengths, gaps and suggestions.
  • Teacher review: teachers see the AI draft, edit scores and feedback, and approve before anything is released. Students never see AI draft fields or unapproved results.
  • Reports and analytics: released results come with a downloadable PDF feedback report, and teachers get analytics on their own classes.
  • Security: it includes JWT auth, optional TOTP two-factor login, and role and ownership checks on every endpoint.

How we built it

  • Backend: FastAPI, SQLAlchemy 2, Alembic migrations and PostgreSQL, with business logic in services and thin routers.
  • Auth: JWT with scoped tokens (access versus 2FA), bcrypt through passlib, TOTP through pyotp, and rate limiting on failed logins and 2FA attempts.
  • AI grading: LangChain's ChatGroq, with LLM output validated as JSON (required keys, score within 0 to the question's marks, lists of strings). It retries once, and if the output is still invalid it flags the answer for manual grading.
  • Documents: PDF upload checks (magic bytes, 10 MB limit, random filenames), optional OCR fallback for scanned work, and fpdf2 for feedback reports.
  • Frontend: Next.js 14 (App Router), React and Tailwind, with API calls going through a same-origin /api proxy.
  • Process: we used an AGENTS.md with project rules and small, focused commits, and logged AI-assisted work in AI_DISCLOSURE.md.

Challenges we ran into

  • Silent failures: optional routers load defensively so auth stays up, but that also hid errors. A syntax error in the assignments router silently disabled the whole module.
  • Login bug: submissions has two foreign keys to users (the student and the releasing teacher), which made SQLAlchemy's relationship mapping ambiguous. Every query on User returned a 500, and the UI only showed a generic "Login failed".
  • Trusting AI output: LLM responses can be malformed or out of range, so we needed strict validation, a retry and a manual-review fallback.
  • Privacy boundaries: making sure a student can never receive draft or unapproved fields took careful schema design and tests.
  • Deployment: a preview proxy, a platform-managed database schema and Alembic had to work together without creating duplicate tables.
  • Frontend structure: we had both a root app/ folder and a parallel frontend/src/app tree, so some pages were unreachable until we re-exported them.

Accomplishments that we're proud of

  • A human-in-the-loop design where the AI never releases a grade on its own.
  • Server-side enforcement of deadlines, ownership, roles and release status, rather than relying only on the UI.
  • A grading pipeline that fails safely: invalid AI output is flagged for manual grading instead of being trusted.
  • Security hardening beyond the basics: scoped JWTs, 2FA, rate limiting, security headers and request IDs.
  • Debugging and fixing the login failure from a single misleading error message down to its root cause.
  • Clear documentation and an AI-disclosure trail.

What we learned

  • Generic error messages hide real bugs, and surfacing the actual failure saves hours.
  • Optional or defensive loading needs logging and tests, otherwise whole features disappear unnoticed.
  • LLMs are useful drafters but need schema validation and a human check before their output affects students.
  • Small, focused commits make debugging and review much easier.
  • Privacy and access control are easiest to get right when designed into the data model from the start.

What's next for GradeLens

  • Finish the student experience: a complete assignment list and submission screen, deadline countdowns and notifications.
  • Better teacher tools: multiple-choice authoring, reusable rubric templates, bulk review and side-by-side comparison of AI and teacher scores.
  • Stronger AI grading: confidence scores, per-criterion scoring, teacher feedback to improve prompts, and support for handwritten work through improved OCR.
  • Production readiness: shared rate limiting, httpOnly cookie sessions in place of localStorage, private object storage for uploads and a live deployment with monitoring.
  • Integrations: LMS connections (Google Classroom, Moodle), CSV grade export and multi-language support.
  • Fairness: bias checks and audit logs for AI-assisted grading decisions.

Built With

Share this project:

Updates

Submission history