ReviewLens

ReviewLens is an interactive, AI-powered code review and deliberate practice platform.

Comment

Inspiration

With code generation tools like GitHub Copilot, ChatGPT, and Claude, developers write and merge code faster than ever. But that speed introduces a real problem: developer skill atrophy. Engineers often accept AI suggestions without understanding the architectural trade-offs, potential runtime failures, or security implications.

At the same time, traditional linters and automated code review bots only point out what failed (a syntax error or a formatting rule) or dump a generic patch. They act like punitive checkers rather than mentors.

ReviewLens grew out of a simple thesis:

"Don't just review my code. Teach me to become a better reviewer."

We wanted to turn code review from a passive linting chore into active learning and deliberate practice, connecting static analysis with foundational software engineering principles.

What it does

ReviewLens is an interactive code review and deliberate practice platform that reviews code snippets (such as real-world enterprise TypeScript) and guides engineers through a structured learning workflow:

  1. Structured Breakdown by Severity and Domain: Categorizes issues across engineering domains (Bug Detection, Security, Maintainability, Type Safety, Testing, Performance) and severity levels (Critical, High, Medium, Low).
  2. Root-Cause Context ("Why Does This Matter?"): Explains concrete production runtime consequences instead of abstract warnings (for example, how an unhandled undefined access throws a TypeError that halts a checkout flow).
  3. First Principles ("Engineering Principle"): Maps each defect to established software engineering principles (Null Safety & Defensive Checks, Fail-Fast, Single Responsibility, Boundary Validation).
  4. Suggested Improvement and Diff: Shows clear, copyable, syntax-highlighted solutions.
  5. Deliberate Practice ("Challenge Me"): Generates a contextual multiple-choice quiz for each finding to test comprehension immediately.
  6. Deterministic Scoring and In-Depth Explanations: Evaluates answers client-side with zero latency and zero scoring hallucination, explaining why the correct choice works and why the alternatives fail.
  7. Skill Scorecard and Dashboard: Tracks developer growth across five core dimensions (Bug Detection, Security, Maintainability, Type Safety, Testing), updating deterministically (+3 points per solved challenge, capped at 100) with animated progress bars and local storage persistence.
  8. Preloaded Demo Example: Includes OrderService.ts, a realistic enterprise TypeScript snippet with high-impact bugs for one-click testing.
  9. Dual-Provider Architecture: Runs offline in deterministic Mock Mode by default (zero latency, zero dependencies for live demos), with an optional Live AI Mode supporting Google Gemini (gemini-1.5-flash, gemini-2.0-flash) and OpenAI (gpt-4o-mini).

How we built it

We designed ReviewLens as a modular client-side application with clean layer separation:

  • Frontend & UI: Built with React 19, TypeScript (strict mode, zero un-narrowed any), Vite 6, and Tailwind CSS v4, styled with Lucide React icons.
  • Layered Architecture:
    • Presentation Layer: Accessible, modular components (App, Header, SkillDashboard, CodeInput, ReviewLoadingState, FindingsList, FindingCard, FindingDetail, ChallengeModal, SettingsModal, ErrorAlert).
    • Service Layer: Decoupled application services (ReviewService, SkillService, ChallengeService) isolating business logic from the UI.
    • AI Provider Abstraction: A unified ReviewProvider interface with two implementations: MockReviewProvider (for deterministic offline operation) and LLMReviewProvider (for direct browser-based API calls to Gemini and OpenAI).
    • Domain & Validation Layer: Typed data models validated at runtime with Zod (CodeReviewSchema, FindingSchema, ReviewChallengeSchema, SkillScoresSchema).
  • AI Pipeline and Prompt Design: A system prompt assigning the model the persona of a senior staff engineer and empathetic educator, requiring strictly formatted JSON output.
  • Defensive Ingestion (jsonExtractor): A custom extractor that strips markdown fences, conversational commentary, and irregular spacing, reinforced by Zod refinements that enforce unique IDs across findings and quiz answers to prevent React key collisions.
  • Credential Safety: User API keys stay exclusively in browser localStorage and never hit external telemetry. All outbound error messages run through a sanitizer that replaces matching keys with [REDACTED_API_KEY].
  • Testing and Verification: A test suite of 212 automated tests across 20 files with Vitest and React Testing Library, plus a Playwright automation script (recordDemo.js) that drives the browser through the full user journey and records a demo video in WebM format.

Challenges we ran into

  1. Unpredictable LLM Output Formats: Even with explicit prompt constraints, LLMs often wrap JSON in markdown blocks, insert conversational preambles, or generate duplicate IDs (finding-1, identical option keys). Duplicate IDs break React list rendering and selection state. We handled this by pairing a defensive regex JSON extractor with strict Zod refinements (.refine()).
  2. Preventing Hallucinations During Quiz Grading: Having an LLM grade multiple-choice answers at quiz time adds latency, costs tokens, and risks hallucinated scores. We solved this by having the model generate both the question and the correct answer key during the initial review pass. The modal evaluation runs entirely client-side, making grading instant and 100% deterministic.
  3. Demo Reliability and the 10-Second Test: Network lag, rate limits, or expired keys can easily break a live hackathon presentation. Making the deterministic Mock Provider the default mode guaranteed a reliable, zero-latency presentation while keeping Live AI available behind a simple toggle.
  4. Balancing Educational Depth with Visual Clutter: Explaining principles like Single Responsibility or Null Safety without overwhelming the user took several UI iterations. We settled on progressive disclosure: summary card → highlighted snippet → "Why Does This Matter?" container → engineering principle → modal quiz.
  5. Error Sanitization: Network rejections and API errors sometimes echo request headers or authorization tokens. We built a scrubbing layer to sanitize exception messages before they reach UI banners or console logs.

Accomplishments that we're proud of

  • Turning Code Review into Active Learning: Creating a smooth workflow that pairs code feedback with engineering principles and interactive practice.
  • High Test Coverage and Stability: 212 passing unit and integration tests across 20 files, backing every core state transition, parsing path, and service boundary.
  • Six-Pass Independent Code Review: Conducting a formal code audit across Correctness, TypeScript strictness, AI boundary safety, Security, UX, and Scope, resolving all identified issues (REV-001 through REV-008).
  • Fast Onboarding and Smooth Demo Flow: Hitting our target of communicating the core value within 10 seconds of landing on the app, backed by a sub-90-second end-to-end walkthrough and an automated Playwright recording script.
  • Zero Backend Dependencies: Running the full platform directly in the browser via npm run dev, with no database setup or external middleware required.

What we learned

  • AI as a Cognitive Scaffold: Generative AI provides the most enduring value when it helps developers build intuition rather than simply writing the code for them.
  • Defensive Boundaries Around LLMs: Treating LLM output as untrusted input is essential. Combining prompt structure, robust extraction, and runtime schema validation (like Zod) makes client-side AI applications stable in production.
  • The Value of Deterministic Fallbacks: Designing a mock provider is not just a hackathon safety net; it provides an excellent foundation for automated testing, offline development, and reliable demos.
  • Effective Gamification Needs Substance: Skill progression is only motivating when points reflect genuine comprehension milestones rather than vanity activity metrics.

What's next for ReviewLens

  • IDE Extensions (VS Code & JetBrains): Bringing "Why Does This Matter?" context and inline challenges directly into the editor as developers write and stage commits.
  • GitHub App & PR Bot: Integrating with CI pipelines to comment on pull requests with structured explanations and practice prompts.
  • Team Dashboards & Skill Analytics: Giving engineering leads aggregated visibility into recurring skill gaps across teams (such as async race conditions or missing input validation) and suggesting targeted practice modules.
  • Expanded Language Support: Broadening our review rules and pedagogical datasets beyond TypeScript and JavaScript to Python, Go, Rust, Java, and C#.
  • Spaced Repetition: Scheduling refresher quizzes on previously missed concepts across days or weeks to reinforce long-term retention.
  • In-Browser Interactive Sandboxes: Letting developers write and verify code fixes directly in an embedded WebContainer environment with instant unit tests, moving beyond multiple-choice prompts.

Built With

Share this project:

Updates

Submission history