ClassCompass

From student work to a clear next teaching step

Inspiration

We took a lot of inspiration form our daily lives, as some of us in the group have personal connections with elementary school teachers who are struggling with

When the decline is this widespread, teachers need a faster way to see what is going wrong in their own classrooms. A failing score only tells a teacher that a student is struggling, not why. The student may not understand the concept, may have made a small arithmetic slip, or may not have had help when they needed it.

We built ClassCompass to close that gap. It turns student work into a clear next teaching step, shows the evidence behind it, and leaves the decision with the teacher. Our goal is for teachers to spend less time on lesson planning and more time with their students.

What it does

ClassCompass reads student worksheets and shows how each student's understanding changes over time. The core loop is:

Student work → understanding → teaching decision → lesson change → follow-up evidence

Analyzes worksheets with AI. It transcribes answers and working, and flags anything it can't read clearly.
Identifies struggling topics. Skills like equivalent fractions and fraction addition move through four stages: Needs support, Getting there, Works independently, and Not enough evidence.
Shows easy-to-read graphics. Charts show skill stages, class-wide patterns, and each student's progress over time.
Checks the math itself. Our own code verifies fraction arithmetic, so correctness doesn't depend on the AI alone.
Links every suggestion to evidence. Teachers can view the original scan, correct a misreading, and confirm or change an interpretation.
Suggests lesson plan improvements. Changes fit the existing lesson's timing and constraints, and teachers choose which ones to save.
Answers questions. A classroom assistant uses saved work, goals, and lessons to answer, with links back to its sources.

Nothing is applied without the teacher's approval.

How we built it

Front end: Next.js 16, React 19, and TypeScript, styled with Tailwind CSS and Radix UI, with custom React/SVG charts. PDF.js displays uploaded documents as evidence.
Back end: Next.js Route Handlers on Node.js handle uploads, AI requests, teacher corrections, and saved plans.
Data and auth: Supabase provides PostgreSQL, teacher sign-in, and private file storage, with row-level security so each teacher only sees their own data.
AI: The DeepSeek API reads worksheet images and generates findings, lesson suggestions, and assistant replies. We use an existing model with no custom training.
Validation: Zod schemas and custom domain rules check AI outputs against the math, the evidence, and lesson constraints.
Testing: Vitest, Playwright, and GitHub Actions.

Challenges we ran into

Handwriting isn't always readable. We made an unclear scan trigger a review instead of being marked wrong.
A right answer doesn't prove understanding. A correct answer with no work shown doesn't establish the method, and a student can get equivalent fractions right but still make an addition mistake. Our rules had to account for both.
Making AI output trustworthy. Model responses had to become usable, checkable data, so we built validation and kept the teacher as the final decision-maker.
Keeping lesson suggestions realistic. Changes had to respect timing, groupings, and fixed dates instead of proposing an entirely new lesson.
Reliable processing. We added saved jobs, bounded retries, duplicate-request protection, and rejection of outdated results.

Accomplishments that we're proud of

Traceable evidence: every finding connects back to a specific student response.
Understanding from explicit rules, not an AI-generated percentage.
Teacher corrections that keep the original reading distinguishable from later revisions.
A full evidence-to-lesson workflow, from a scanned worksheet to a saved lesson version, not just a call to an AI API.
A demo dataset of 8 fictional students, 5 assignments, 40 worksheet scans, and 120 responses.

What we learned

Teacher control and transparency matter as much as accuracy.
Making sure the AI responses are accurate, traceable, and safe to act on, and that our AI was flagging data it was unsure of rather than running with it.
Missing evidence should show up as a gap, not as a low score.
Being honest about limits matters. Our understanding stages are provisional interpretations, not a validated mastery score.
We learned that working with AI is an ongoing back-and-forth: prompt, check, correct, and repeat.

What's next for ClassCompass

Extract data from educational platforms like Google Classroom, Canvas, and Brightspace, so teachers don't have to upload worksheets manually.
Support a variety of grade levels, expanding from elementary into middle school.
Network between teachers, so teacher profiles can connect to share struggles and solutions.
Evaluate in real classrooms. So far we've only used fictional data, so we haven't measured learning gains or time savings yet.

Built by Ryan, Yan, Olive, and Chloe.