Contextual Codebase Explainer

Here is the concise, hackathon-ready content for your project submission. It highlights your technical depth and the "Dhaasu" features we added.

Inspiration Developers spend more time reading code than writing it. Onboarding onto a massive, undocumented codebase feels like navigating a dark cave without a map. We wanted to build a "GPS for Code"—something that doesn't just describe the code, but visualizes the logic and warns you of traps before you fall into them.

What it does Contextual Codebase Explainer is an AI-powered co-pilot that:

Visualizes Logic: Generates interactive Mermaid.js flowcharts of complex functions.

Health Checks: Assigns a 0-100 Health Score and a "Brutal Verdict" on code quality.

Modernizes: Identifies "ugly" legacy code and provides a side-by-side AI Smart Refactor.

Stays Contextual: Uses your project's specific Style Guides to ensure analysis follows team rules.

Safety First: Compares versions to catch Backward Compatibility breaks.

How we built it Frontend: A modern, glassmorphism UI built with HTML5, CSS3 (Inter font), and JavaScript.

Backend: Flask (Python) handles file uploads (ZIP/Single files) and data processing.

AI Engine: Integrated Google Gemini 2.0 Flash for high-speed, 20k+ token context window analysis.

Visualization: Mermaid.js for rendering dynamic, color-coded architecture diagrams.

Challenges we ran into The Mermaid Parse Error: Handling special characters in code (like parentheses and commas) within diagram labels was breaking the UI. We solved this by implementing strict double-quote label sanitization in the Python backend.

Context Windowing: Passing large codebases to AI can be expensive. We optimized this by creating a "Master Prompt" that extracts all features in a single API call to save quota and reduce latency.

Accomplishments that we're proud of Successfully implemented a side-by-side refactoring tool that actually improves code complexity.

Achieved a High-Definition diagram output that remains readable even for deep logic paths by using custom SVG scaling and line-break logic.

What we learned We learned the importance of prompt engineering for structured data. Getting an AI to return valid Mermaid syntax consistently required building a robust parsing helper and strict "Critical Rules" within the system prompt.

What's next for Contextual Codebase Explainer IDE Extension: Porting this logic into a VS Code extension for real-time analysis.

Repo Mapping: Automatically scanning an entire GitHub URL without requiring a manual ZIP upload.

Multi-Agent Review: Having two AI "agents" debate the code—one to find bugs, one to defend the logic—to provide a more balanced "Mentor Answer."