Citation Gym

Train the reasoning behind the citation.

Comment

Inspiration

Citation Gym was inspired by a simple problem: students are often told to “support your claim with evidence,” but they rarely get meaningful practice with the reasoning step between selecting a quote and making an argument.

Most writing tools focus on grammar, rewriting, or generating an answer. Citation Gym focuses on the skill that matters before polished prose: making a defensible claim, choosing relevant evidence, and explaining exactly how that evidence supports the claim.

We also wanted to solve the teacher side of the problem. A teacher can identify weak reasoning in an individual response, but it is much harder to spot patterns across an entire class—such as students repeatedly making claims that go beyond their sources or dropping quotations into an answer without explanation. Citation Gym turns those recurring reasoning patterns into actionable classroom insights.

What it does

Citation Gym is a role-based learning platform for source-grounded reasoning.

Teachers can:

  • Create classrooms and share join codes with students.
  • Create assignments with a prompt and an assigned reading/source set.
  • View a live submission queue with draft, submitted, returned, resubmitted, and reviewed states.
  • Review student work, add written feedback, mark work reviewed, or return it for revision.
  • View assignment-level reasoning insights that identify recurring patterns across student coaching sessions.
  • Drill into a reasoning pattern and see the latest affected work for each student.

Students can:

  • Join a class using an invite code.
  • Read assigned passages and build a claim supported by selected evidence.
  • Explain the connection between their evidence and claim.
  • Save drafts, request AI coaching, submit work, and review feedback.
  • Start a versioned revision after a teacher returns work, preserving the original submission history.
  • Receive plain-language evidence-alignment guidance rather than a vague “this is wrong” message.

The AI Coach is source-grounded. It evaluates the student’s selected evidence, checks whether the claim is supported by those passages, identifies a reasoning signature when appropriate, and gives one focused next action.

How we built it

Citation Gym is built with:

  • Next.js 16 with the App Router and TypeScript.
  • Clerk for authentication and role-aware student/teacher experiences.
  • Neon PostgreSQL and Prisma for relational data, migrations, and authorization-aware queries.
  • shadcn/ui and Tailwind CSS for the responsive interface, sidebar, cards, badges, breadcrumbs, and theme support.
  • LangGraph and LangChain for a controlled AI coaching workflow.
  • AI/ML API through its OpenAI-compatible interface for model access.

Our core data model connects organizations, classrooms, enrollments, assignments, readings, passages, attempts, immutable attempt versions, evidence links, coaching feedback, reasoning signatures, and teacher reviews.

The AI pipeline is deliberately structured instead of being a single unconstrained prompt:

flowchart LR
  A["Student claim + selected evidence"] --> B["Verify evidence"]
  B --> C["Evaluate claim–evidence alignment"]
  C --> D["Generate focused coaching"]
  D --> E["Ground and sanitize response"]
  E --> F["Persist feedback + reasoning signature"]
  F --> G["Student guidance + teacher insights"]

This workflow ensures that feedback remains tied to assigned sources. The final grounding step only accepts passage IDs selected by the student and normalizes the model output before it is saved.

How we used OpenAI Codex and GPT-5.6

OpenAI Codex was a core part of our development workflow. We used Codex as a collaborative engineering partner throughout the project: to inspect the existing Next.js codebase, plan feature slices, implement full-stack changes, debug production issues, validate database and route behavior, and improve the project documentation.

GPT-5.6 and Codex accelerated development in several concrete ways:

  • Architecture and technical planning: Codex helped translate the product idea into implementable slices: authentication and roles, classroom enrollment, assignments, immutable attempt versions, teacher review workflows, AI coaching, and teacher insights.
  • Full-stack implementation: Codex helped create and connect Next.js pages, protected API routes, Prisma queries, Clerk-based role handling, shadcn/ui components, and Neon PostgreSQL persistence.
  • Debugging real integration issues: We used Codex to investigate Prisma migration mismatches, unique-email conflicts between Clerk and the application database, static/demo routes that had not yet been connected to live data, route authorization issues, and Vercel build failures caused by generated Prisma client files.
  • Agentic AI design: Instead of treating the AI coach as a single prompt, Codex helped design and implement a controlled LangGraph workflow with separate evidence verification, claim–evidence alignment evaluation, coaching, and grounding steps.
  • Quality checks: Codex ran TypeScript validation, Next.js route-type generation, production builds, and codebase searches to catch issues before deployment.
  • Documentation and presentation: Codex helped produce the project README, architecture diagrams, technical explanations, demo flows, and this Devpost narrative.

Codex accelerated implementation, but the key product decisions remained intentional and human-led. We chose to focus Citation Gym on evidence-based reasoning rather than generic writing assistance; we chose a teacher review loop with versioned revisions; and we chose a constrained, source-grounded agent workflow instead of an unconstrained multi-agent system. Those decisions shaped how GPT-5.6 was applied in the product.

The result was a faster iteration cycle: we could identify a broken flow, inspect the real code and data model, implement a scoped fix, validate it, and return to testing without losing momentum.

Challenges we ran into

One major challenge was designing a workflow that worked for both students and teachers without turning into two disconnected products. Students need a low-friction writing experience, while teachers need a clear overview of classroom progress and recurring reasoning issues.

We also had to carefully model the attempt lifecycle. A student should be able to draft, submit, receive feedback, revise, and resubmit without losing the original work. We solved this with immutable attempt versions and explicit states such as SUBMITTED, RETURNED, RESUBMITTED, and REVIEWED.

Another challenge was keeping AI feedback trustworthy. A general-purpose LLM can give plausible but unsupported feedback, especially when evaluating source-based work. We addressed that by separating evidence verification, alignment evaluation, coaching, and grounding into controlled LangGraph nodes.

Finally, we worked through deployment and production concerns, including Prisma client generation on Vercel, role-aware authorization, Clerk identity synchronization, Neon database migrations, and making sure generated Prisma files are not incorrectly committed to Git.

Accomplishments that we're proud of

We are proud that Citation Gym is more than a chat box attached to an assignment.

  • We built a complete teacher-to-student workflow: classroom creation, enrollment, assignment creation, drafting, AI coaching, submission, teacher review, revision, and resubmission.
  • We created immutable revision history so students can improve without overwriting their original reasoning.
  • We made AI feedback source-grounded and actionable instead of generic.
  • We added a dedicated evidence-alignment step that explains whether a student’s claim follows from their selected passages.
  • We turned individual coaching results into assignment-level teacher insights.
  • We designed role-specific navigation and protected routes so students and teachers only see the tools relevant to them.
  • We deployed the project with a production-ready stack using Clerk, Prisma, Neon, Vercel, and AI/ML API.

The most rewarding part is seeing a teacher move from “I have many submissions to read” to “I can see the reasoning pattern my class needs help with.”

What we learned

We learned that agentic AI is most useful when it is constrained by a clear educational workflow.

Rather than building a large, open-ended multi-agent system, we found that a small graph of specialized steps is more reliable:

  • validate the evidence first;
  • assess the claim–evidence relationship;
  • generate concise feedback;
  • verify and sanitize the output before showing it to a student.

We also learned that data modeling is central to educational products. The difference between a draft, submission, returned revision, and reviewed work is not just a UI detail—it determines what each user can do and what history must be preserved.

On the product side, we learned that teachers need pattern recognition, not only individual feedback. A single student’s coaching result is useful; a summary showing that several students are making the same reasoning mistake is much more actionable.

What's next for Citation Gym

Our next steps are focused on making Citation Gym even more useful in real classrooms:

  • Add cross-class and organization-level insight dashboards.
  • Add teacher-configurable rubrics and assignment-specific coaching criteria.
  • Add subject-specific tools, starting with a math/algebra verifier for quantitative reasoning.
  • Let teachers create reusable source-set and assignment templates.
  • Add richer analytics for revision progress and improvement over time.
  • Add notifications for new submissions, returned revisions, and completed reviews.
  • Add exportable teacher reports for classroom assessment.
  • Add a polished demo workspace with seeded data for judges and onboarding.
  • Expand the AI Coach with carefully scoped tools while preserving source grounding, privacy, and teacher control.

Built With

  • clerk
  • clerkauth
  • codex
  • gpt-5-6-sol
  • langgraph
  • neon-postgresql
  • nextjs
  • openai
  • prisma-orm
  • shadcnui
  • typescript
  • vercel
Share this project:

Updates