ClassTrace

ClassTrace uses GPT-5.6 to map how students reason, group evidence-backed misconceptions, generate teacher-approved interventions, and verify whether understanding transfers to a new problem.

Comment

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

Teachers can quickly see who answered a question incorrectly, but a wrong answer rarely explains why the learner is wrong.

Two students may submit the same final answer while following completely different reasoning paths. One may confuse area with circumference, another may apply linear scaling to a squared quantity, and another may understand the concept but make a small arithmetic mistake. When these responses are treated as the same error, reteaching becomes generic and less effective.

ClassTrace was built to help teachers see how an entire class is thinking—not just who got the answer right or wrong.

What ClassTrace does

ClassTrace is an evidence-grounded reasoning analysis platform for teachers.

A teacher provides:

  • an assessment question;
  • an expected reasoning guide or rubric;
  • up to 12 de-identified typed or image-based student responses.

GPT-5.6 analyses the observable reasoning in each response and ClassTrace converts the results into a visual Trace Map showing the different reasoning patterns across the class.

From there, teachers can:

  • inspect exact evidence from each learner’s submitted work;
  • review confidence and alternative hypotheses;
  • approve, rename, move, merge, flag, or restore AI-generated groupings;
  • generate a targeted intervention for an approved reasoning pattern;
  • review the intervention before learners receive access;
  • evaluate whether a learner can transfer the corrected idea to a new problem.

ClassTrace does not simply generate feedback or check whether the final answer is correct. It closes the instructional loop:

Student work → reasoning map → teacher review → targeted intervention → transfer evidence

The verified demonstration

In the production demonstration, 12 learners responded to a question about how the area of a circle changes when its radius doubles.

ClassTrace identified:

  • 5 distinct possible misconception clusters;
  • 4 learners applying linear scaling directly to area;
  • 3 learners using circumference as area;
  • additional formula, exponent, and comparison errors;
  • 2 learners demonstrating correct understanding.

The teacher inspected the exact evidence behind the largest cluster and approved a targeted circle-area intervention.

The learner initially predicted that doubling the radius would double the area. After using the interactive radius explorer, the learner explained that area scales with the square of the radius.

A new transfer problem then changed the scale factor from 2 to 3. The learner correctly explained that multiplying the radius by 3 multiplies the area by (3^2 = 9).

GPT-5.6 evaluated the explanation—not only the final number—and marked this single completed transfer check as resolved at 99% confidence.

Why it is different

Most AI education products focus on tutoring one student, generating lessons, or grading final answers.

ClassTrace focuses on a different problem:

What reasoning pattern produced this answer, how widespread is it across the class, and did the targeted intervention actually change the learner’s understanding?

Its core differentiators are:

  1. Class-level reasoning intelligence
    Multiple student responses are compared and grouped by shared reasoning evidence.

  2. Evidence-grounded analysis
    Confident diagnoses must point back to exact excerpts from the submitted work.

  3. Teacher-in-the-loop control
    The teacher remains responsible for instructional decisions and can revise every AI-generated result.

  4. Safe intervention generation
    GPT-5.6 returns validated structured configuration. ClassTrace renders trusted React components instead of executing arbitrary model-generated code.

  5. Conceptual transfer verification
    A correct final answer is not enough. The learner must explain the concept in a new situation.

How GPT-5.6 is used

ClassTrace uses GPT-5.6 through the OpenAI Responses API and Structured Outputs.

GPT-5.6 performs:

  • multimodal interpretation of typed and image-based student work;
  • observable reasoning reconstruction;
  • possible misconception hypothesis generation;
  • evidence-grounded cohort clustering;
  • targeted intervention configuration;
  • transfer-response evaluation.

The live class-analysis pipeline uses two concurrent, request-specific six-response batches. Each batch enforces exact response IDs and structured schemas.

If one six-response batch times out, ClassTrace preserves the successful batch and splits only the slower group into two bounded three-response requests. All results are then merged and validated globally.

The product verifies:

  • every response appears exactly once;
  • confident analyses contain verbatim supporting evidence;
  • unknown or duplicate response IDs are rejected;
  • low-confidence or insufficient-evidence work can require teacher review;
  • model-generated executable content is rejected.

How Codex contributed

Codex was used throughout the build to help implement and verify:

  • the Next.js and TypeScript application architecture;
  • GPT-5.6 Structured Outputs and Zod schemas;
  • streamed analysis-stage orchestration;
  • timeout and bounded recovery logic;
  • the visual Trace Map;
  • teacher-review controls;
  • intervention and transfer workflows;
  • browser-local persistence;
  • duplicate paid-analysis protection;
  • privacy and evidence-export safeguards;
  • responsive design and accessibility;
  • unit and Playwright browser testing;
  • Vercel deployment readiness;
  • final documentation and submission preparation.

The builder personally defined:

  • the ClassTrace product concept;
  • the teacher-first workflow;
  • evidence and uncertainty requirements;
  • teacher-control boundaries;
  • privacy rules;
  • the interactive intervention model;
  • the visual direction;
  • the demonstration scenario;
  • the final submission story.

Product design and safety

ClassTrace is designed as a teacher-controlled instructional tool, not an autonomous grading authority.

Important boundaries include:

  • teachers remain responsible for instructional decisions;
  • the product suggests possible reasoning patterns rather than labelling intelligence or ability;
  • student text is treated as untrusted input;
  • uploaded images are used only for the active request and are not persisted;
  • image bytes and Base64 data are excluded from browser storage and evidence exports;
  • low-confidence interpretations can be routed to teacher review;
  • no arbitrary model-generated JavaScript, HTML, or executable code is run.

Reviewer experience

ClassTrace provides two clearly labelled modes:

Prepared showcase

An instant deterministic walkthrough of the full experience with no model call required.

Live GPT-5.6 analysis

A real evidence-grounded analysis with run provenance. Detailed class analysis normally takes approximately one to two minutes.

Successful assessments are stored locally in the browser and can be resumed without making another paid model request. Identical assessments are fingerprinted so users can open an existing result before deliberately choosing to run the analysis again.

Technical stack

  • Next.js App Router
  • React
  • TypeScript
  • Tailwind CSS
  • OpenAI Responses API
  • GPT-5.6
  • Codex
  • Structured Outputs
  • Zod
  • Node.js
  • Vitest
  • Playwright
  • Vercel

Challenges

The most significant engineering challenge was making a reasoning-heavy multimodal workflow both trustworthy and production-resilient.

Early model responses could satisfy a broad schema while omitting some learners. ClassTrace now uses request-specific exact-length schemas, known response IDs, deterministic membership validation, and a single bounded repair path.

Model latency also varied across production runs. The final architecture uses concurrent request batches and bounded timeout recovery without repeating already successful work.

Another challenge was preventing AI-generated educational content from becoming executable code. The intervention generator returns only validated configuration for trusted components.

Accomplishments

I am proud that ClassTrace is not just a prompt wrapper or chat interface. It is a complete teacher-to-learner workflow with:

  • a production deployment;
  • real GPT-5.6 analysis;
  • evidence validation;
  • human review and reversible edits;
  • safe intervention generation;
  • an interactive learning experience;
  • conceptual-transfer evaluation;
  • prepared and live reviewer modes;
  • responsive desktop and mobile experiences;
  • automated unit and browser testing.

What I learned

Building ClassTrace reinforced that trustworthy education AI requires more than a confident model response.

The system must preserve uncertainty, connect claims to evidence, let educators correct the AI, protect student data, and evaluate whether learning transfers beyond the original question.

I also learned that model orchestration must be designed for variable latency and incomplete outputs rather than assuming every structured request will behave perfectly.

What is next

Future work could include:

  • educator-led evaluation across more mathematical concepts;
  • additional trusted interactive intervention components;
  • broader support for handwriting and multilingual work;
  • class-level transfer batches;
  • secure school accounts and cross-device persistence;
  • LMS integrations;
  • longitudinal misconception tracking.

ClassTrace begins with one focused promise:

Traditional grading shows who got it wrong. ClassTrace shows why, what to teach next, and whether understanding transferred.

What we learned

What's next for ClassTrace

Built With

  • ai
  • api
  • codex
  • css
  • edtech
  • education
  • gpt-5.6
  • multimodal
  • next.js
  • node.js
  • openai
  • outputs
  • playwright
  • react
  • responses
  • structured
  • tailwind
  • typescript
  • vercel
  • vitest
  • zod
Share this project:

Updates