Detour: Cognitive Wrong-Turn Diagnosis Engine

Cognitive Wrong-Turn Diagnosis Engine — Pinpoints the exact premise divergence and root misconception in flawed human reasoning.

Comment

Detour: Cognitive Wrong-Turn Diagnosis Engine

Pinpoints the exact step where your reasoning went wrong — not just what the right answer is.

Live Demo

Project Overview

Detour is an AI diagnostic engine that pinpoints the exact cognitive step where a human's reasoning went wrong. Instead of acting as an answer vending machine or delivering generic lecture summaries, Detour isolates the precise premise divergence, identifies the underlying misconception, and provides targeted mental-model corrections.

The Problem & Value Proposition

When learners, software engineers, and researchers encounter flawed conclusions in logic, mathematics, algorithmic design, or system architecture, standard AI systems either output the final solution or re-explain the entire textbook topic. This creates an illusion of competence: users read the correct derivation, nod along, but fail to identify their own faulty assumption.

Detour treats reasoning flaws like software bugs:

  1. It validates the user's initial problem setup.
  2. It traces the user's attempt step by step.
  3. It locates the first divergence point (the wrong turn).
  4. It extracts cited textual evidence from the attempt.
  5. It names the exact cognitive fallacy or misapplied rule.
  6. It provides a minimal conceptual fix and a test scenario to verify understanding.

Why Detour?

Standard educational tools tell you what the right answer is. Detour tells you how your brain arrived at the wrong one.

By analyzing the user's explicit reasoning chain against the problem constraints, Detour performs surgical root-cause analysis:

  • No Canned Explanations: Diagnoses are derived specifically from the user's unique reasoning path, not generic template responses.
  • Support for Unknown Answers: If the user does not know the correct answer, Detour operates in self-determined mode, first establishing the ground-truth derivation and then isolating the user's divergence.
  • Noise and Abuse Protection: Built-in heuristic and AI pre-filters eliminate keyboard mash and gibberish without wasting model quota or polluting history.
  • Session Isolation: Each user's diagnostic history is securely partitioned in Cloud SQL, protected behind server-side Google OAuth session tokens.

Detour bridges the gap between making a mistake and genuine conceptual mastery.

Architecture

The Detour architecture follows a 4-stage pipeline:

  1. Frontend Client (React 19): Captures problem statements, reasoning attempts, optional ground truth, displays a continuous anatomical brain sketch loader, renders structured diagnostic notebook cards, and manages isolated user histories.
  2. Security Gateway (FastAPI): Validates session cookies, enforces a rolling 7-request hourly quota per user, screens out gibberish payloads with regex heuristics, and repairs model output JSON strings.
  3. Reasoning Engine (Vertex AI - Gemini 2.5 Flash): Executes prompt-engineered diagnostic inference under low temperature (0.2) to deterministically pinpoint cognitive divergence.
  4. Persistent Storage (Cloud SQL MySQL 8.0): Connects via Unix sockets to persist user profiles, OAuth metadata, and structured diagnosis records with strict multi-tenant isolation.

Core Features

  • Surgical Wrong-Turn Pinpointing — Highlights the exact sentence, formula step, or code line where the reasoning diverged from ground truth.
  • Misconception Classification — Labels the underlying cognitive root cause (e.g., base-rate neglect, off-by-one boundary flaw, scope confusion, state mutation oversight).
  • Evidence Citation — Direct quote from the user's submitted attempt showing the precise phrase where the flawed logic manifested.
  • Self-Determined Ground-Truth Mode — Toggleable checkbox when the correct solution is unknown. Detour independently solves the problem first before diagnosing the mistake.
  • Minimal Conceptual Fix — Actionable, one-sentence correction that repairs the broken assumption without forcing the user to discard their entire approach.
  • Next Test Move Verification — Generates a targeted follow-up question or edge case to validate that the learner has corrected their mental model.
  • Continuous Brain Outline Animation — Seamless, single-stroke anatomical brain loader that keeps users engaged during inference.
  • Hourly Rate Limiter — Sliding window quota (7 diagnoses per hour per user) with real-time UI pill indicator to ensure fair usage.
  • GIGO & Gibberish Filtering — Intercepts nonsense keystroke mash before model execution, providing randomized witty feedback while saving compute tokens.
  • Direct History Management — Instant diagnosis deletion and history synchronization without intrusive browser popup warnings.

Tech Stack

Layer Technology
AI Models gemini-2.5-flash (Vertex AI, us-central1)
AI SDK google-genai / google-cloud-aiplatform
Backend Framework Python 3.12 · FastAPI · Uvicorn · Starlette
Database & ORM Google Cloud SQL (MySQL 8.0) · SQLAlchemy 2.0 · PyMySQL
Frontend Framework React 19 · Vite · Vanilla CSS (Paper & Ink Design System)
Hosting & Compute Google Cloud Run (asia-south1)
Container & CI/CD Docker Multi-Stage · Google Cloud Build · Artifact Registry
Authentication Google OAuth 2.0 (Server-side Session Cookies)
Testing Pytest · Pytest-Asyncio (14 unit test suites)
Security & Secrets Google Secret Manager · IAM Least-Privilege Roles

Spin up instructions

Option A — Use the Hosted Version (Recommended)

The application is already live on Google Cloud Run. No local setup required.

  1. Visit the live deployment: Explore Detour
  2. Sign in with your Google account.
  3. Enter your logic problem, your flawed reasoning attempt, and optional known answer (or toggle "I don't have the correct answer").
  4. Click Diagnose Wrong Turn to view the structured cognitive breakdown.
  5. Review your saved past diagnoses in the right-hand history notebook sidebar.

Note: Detour requests access to your Google account name, email, and avatar for authentication and session personalization. No other account data is accessed or stored beyond your diagnosis history within the app.

Option B — Run Locally

  1. Clone the repository and install backend and frontend dependencies:
   git clone https://github.com/Varghese778/Detour__FacePREP__BuildSprint.git
   cd Detour__FacePREP__BuildSprint
   pip install -r backend/requirements.txt
   npm --prefix frontend install
  1. Copy .env.example to .env and configure your credentials:
   GOOGLE_GENAI_USE_VERTEXAI=1
   GOOGLE_CLOUD_PROJECT=your-project-id
   GOOGLE_CLOUD_LOCATION=us-central1
   GOOGLE_APPLICATION_CREDENTIALS=path/to/credentials.json
   DATABASE_URL=mysql+pymysql://user:pass@127.0.0.1:3306/detour
   GOOGLE_CLIENT_ID=your-google-client-id
   GOOGLE_CLIENT_SECRET=your-google-client-secret
   SESSION_SECRET_KEY=your-random-32-byte-secret
  1. Run backend test suite to verify configuration:
   pytest backend/tests -v
  1. Start the backend API server:
   uvicorn app.main:app --app-dir backend --host 0.0.0.0 --port 8080 --reload
  1. In a separate terminal, start the frontend development server:
   npm --prefix frontend run dev
  1. Open http://localhost:5173 in your browser.

Learning Curve

AI & Reasoning Diagnosis

  • Answer-Bias Mitigation — Standard LLMs naturally default to solving the problem and presenting their own derivation. Forcing Gemini 2.5 Flash to act strictly as a diagnostic mirror required precise system persona constraints, instructing the model to map user tokens directly to logical fallacies rather than writing generic solution keys.
  • Self-Determined Branching — When users omit the correct answer, the prompt dynamically switches to a dual-pass evaluation: first generating an internal gold-standard solution, then aligning the user's attempt against that trace to identify the exact step of divergence.
  • Deterministic JSON Validation — LLMs can occasionally return markdown code fences, trailing commas, or unescaped control characters. Implementing a multi-pass regex repair pipeline (_repair_and_load_json) before schema validation ensured 100% crash-free parsing.
  • GIGO Protection — Intercepting nonsensical input or keyboard mash before model invocation was essential. A combination of vowel-ratio checks, consonant-run detection, and fallback schema classification prevented token waste while delivering humorous, non-judgmental guidance to the user.

Cloud & Production Stability

  • Cloud Run Unix Socket Connectivity — Connecting Cloud Run to Cloud SQL MySQL across regions required explicit socket path configuration (/cloudsql/PROJECT_ID:REGION:INSTANCE_NAME) and Cloud SQL Admin API enablement.
  • Session Cookie Domain Matching — Running a unified full-stack container on Cloud Run eliminated cross-site cookie blocking and CORS preflight latency, ensuring Google OAuth session tokens work smoothly on modern browsers with strict third-party cookie policies.
  • Multi-Tenant Data Isolation — All diagnosis queries, history listings, rate-limit counters, and deletions enforce strict server-side WHERE user_id = current_user.id conditions, preventing unauthorized cross-user data access.
  • Container Build Optimization — Using a multi-stage Dockerfile with Node 20 for Vite asset compilation and Python 3.12-slim for runtime execution kept the production image compact and cold-start latency under 1.5 seconds.

Deploy to Cloud Run

Live Endpoint Health Check

Built by Sharon Varghese · FACE Prep Build Sprint 2026

Built With

Share this project:

Updates