Concept Detective AI

Topic page
Login Page
Home page

Inspiration

Honestly it started from a pretty simple complaint: most quiz apps just tell you "wrong" and move on. They don't tell you why you got it wrong, which is the actually useful part. A kid who picks the wrong fraction answer because they added denominators straight across, and a kid who just guessed, get the exact same feedback. That always bugged us.

We also both grew up loving mystery/detective shows, and at some point it clicked that solving a mystery and applying a concept are basically the same mental move , you're not recalling a memorized fact, you're reasoning from evidence to a conclusion. So we figured, why not just make that the whole game.

What it does

Concept Detective AI is a full-stack educational mystery game.

1.Pick a topic (Electricity, Newton's Laws, Photosynthesis, Basic Algebra, or Fractions for the MVP) and a difficulty. 2.The AI generates a case — title, setting, briefing, suspects, and clues. Each clue actually ties back to the concept, it's not just flavor text. 3.You look through the evidence, then submit an answer plus a short explanation of your reasoning. 4.The AI grades the reasoning, not just the answer. If you're wrong it names the specific misconception, like "adds numerators and denominators straight across" instead of just saying incorrect. 5.You can ask for a hint. It nudges you in the right direction without just handing you the answer. 6.Difficulty adjusts as you go — two right in a row and it bumps up, two wrong and it eases off. 7.At the end you get a learning report: accuracy, a detective rank badge, strengths, specific things to review based on your actual misconceptions that round.

It also runs in two modes without any code changes. If you add an Anthropic API key, everything above is generated live by Claude. If you don't, it falls back to hand-written mock case data, so it still fully works offline with no API cost, which honestly ended up being one of the more useful parts for demoing this without wifi issues.

How we built it

Backend: FastAPI, a handful of REST endpoints (generate mystery, submit answer, get hint, generate report), Pydantic for validation. All the AI logic sits in one file, ai_service.py, and every function there has a "live" version that calls Claude and a "mock" version using the canned data, so the routes themselves don't care which mode is active. Session state (score, stage, difficulty, misconception history so far) just lives in memory keyed by a session id , no database, didn't need one for this.

Frontend: Next.js 14, TypeScript, Tailwind. One page basically runs the whole game as a state machine , select topic, load case, show briefing and clues, ask question, show feedback, loop, then show the report at the end. Dark detective theme, amber/red accents, clue cards you click open.

Prompts: the actual prompt design is where most of the thought went , telling the model explicitly not to write trivia, to grade reasoning not just the final answer, and to name a specific misconception instead of a generic "incorrect." The mock data was written to match that exact same shape so both modes teach the same way.

Challenges we ran into

Getting the misconception feedback to be specific instead of generic. It's easy to get an LLM to say "you made an error somewhere," way harder to get "you confused adding fractions with adding whole numbers." We ended up modeling misconceptions as actual structured data (a map from likely wrong answer to specific misunderstanding) instead of leaving it up to the model to freestyle. Making the mock mode feel just as good as live mode. We didn't want anyone testing without an API key to get a worse experience, so the mock cases got written with the same depth as what we were asking the live model for. Difficulty adaptation felt kind of invisible at first — we added a small chip in the UI that updates after every answer so you can actually see it happening instead of it being a hidden mechanic. Handling API failures without breaking a run in progress. Every AI call falls back to mock logic if it errors out, so a bad network call mid-case doesn't just crash everything.

Accomplishments that we're proud of

It's an actual working full stack app, not a mockup — we ran a full session through the API by hand start to finish (generate case, ask hint, wrong answer with correct misconception detected, right answers after, case solved, report generated) and it all worked. Mock mode is genuinely good, not just a fallback screen. Zero setup, zero cost, still fully playable. The misconception detection actually works across five pretty different subjects — circuits, physics, biology, algebra, fractions. The detective theme isn't just a skin, it lines up with the actual mechanic (clues you open, evidence you weigh) instead of being a quiz app wearing a costume.

What we learned

Reframing feedback around "here's the misconception" instead of "wrong/right" is a small change that makes a big difference in how useful it feels. Writing the mock data to match the same shape as the live prompt schema early on saved us a lot of headache later, since it made both modes basically interchangeable. A game mechanic and a learning mechanic can just be the same thing if you pick the right metaphor, instead of bolting a game on top of a quiz.

What's next

More topics ; the whole structure (case template, staged questions, misconception map) generalizes past just these five subjects. Actual accounts/persistence so the report is a history over time instead of one session. A teacher-facing view showing which misconceptions are most common across a class. Difficulty scaling that changes case structure itself (more suspects, red herrings) not just question depth. Mobile pass, maybe a voice/narration mode for younger students.