Heuristic

Generate insightful & intelligent documentation for your code repositories

Comment

What it does

Heuristic is an AI-powered platform that automatically analyzes your code repositories and generates comprehensive, insightful documentation. It goes beyond simple code comments to provide:

  • Intelligent Documentation: Automatically generates clear, structured documentation that explains your code's purpose, architecture, and usage patterns.
  • Refactoring Suggestions: Provides AI-powered recommendations to improve code quality, with specific code examples.
  • Architecture Visualization: Creates mermaid diagrams showing component relationships, data flow, and module dependencies.
  • Multiple Export Formats: Exports documentation as PDF, HTML, Markdown, or JSON with customizable AI-generated cover images.
  • GitHub Integration & Authentication: Seamlessly connects with repositories

How we built it

A web app using Next.js 15 with the App Router; tech stack:

  1. Frontend: Next.js with TypeScript for type safety and Tailwind CSS for responsive design. Shadcn/ui (Radix UI) components to maintain a consistent, professional UI.
  2. State Management: Jotai for atomic state management
  3. AI Integration: The core of the web app uses the Google Gemini AI (Gemini 2.0 flash) via Vercel's AI SDK;
  4. Architecture Diagrams: Utilised AI to generated mermaid diagrams and integrated Mermaid.js to render dynamic architecture diagrams generated from code analysis.
  5. PDF Generation: For documentation exports, a custom PDF function was built using jspdf that supports embedding AI-generated cover images.
  6. GitHub Integration: OAuth flow to authenticated users and connect to GitHub repositories via NextAuth and the Github API SDK (Octokit)

The most challenging and innovative part was designing the AI prompts and schemas that could create befitting UI (& UX) to accurately communicate the app's purpose －analyze code structure and generate meaningful documentation.

Challenges we ran into

  • *App structure *: Creating a correct UI & UX that easily communicates the app's usecases, and reduces friction
  • AI Hallucinations: This was solved by implementing strict validation schemas using Zod.
  • Diagram Generation - Finding the appropriate library to help render the mermaid diagram without dabbling in low-level was a little bit of an hassle.

Features

  • Automatic Documentation Generation: Analyze repositories and generate detailed documentation
  • Generate professional cover images for your documentation
  • Complexity Analysis: Visualize code complexity with metrics
  • Code Quality Scoring: Get an objective measure of your code quality
  • Technical Debt information: Identify TODOs, FIXMEs, and whatnots
  • Multiple Export Formats: Export documentation as PDF (with embedded ai-generated cover image), HTML, Markdown, or JSON

Accomplishments that we're proud of

  • Interactive Architecture Visualization: Created an intuitive way to visualize code architecture that helps developers understand complex systems at a glance.
  • Export Quality: Exporting the generated documentation in PDF, Mardown, JSON and HTML formats.
  • User Experience: Designed an intuitive interface that makes complex code analysis accessible to developers of all experience levels.

What we learned

  • How AI can help optimize existing siloed/fragmented development workflows i.e. in the case of creating a mermaid diagram to visualize the project architecture early-on － that reduces friction in DevExperience and onboarding time of developers working on a new codebase
  • Creating PDF via code - PDFs are pretty much everywhere, creating them via code is/was informative

What's next for Heuristic

  • PR analysis
  • VS Code extension to generate code documentation in-house
  • Functionality to allow users upload generated documentation to their select code repo

Built With

  • ai-sdk
  • framer-motion
  • gemini
  • github-oauth
  • jspdf
  • mermaid.js
  • next.js
  • nextauth
  • radixui
  • tailwindcss
  • typescript
  • zod
Share this project:

Updates