Code Cartographer - AI Code Analysis Tool

Inspiration

As a student learning to code, I noticed my peers relying heavily on Copilot to write code for them without truly understanding what they're building. When they encounter a new codebase - whether it's an open-source project, a class assignment, or an internship project - they're lost. I wanted to create a tool that uses AI differently: not to write code FOR you, but to help you UNDERSTAND code that already exists. In today's AI-driven world, the skill isn't just writing code - it's understanding, analyzing, and learning from existing codebases.

What it does

Code Cartographer is an educational tool that helps students understand complex codebases by:

Explaining code in plain English using Google Gemini AI - like having a senior developer explain the code to you
Mapping relationships between files with interactive visualizations so you can see the big picture
Identifying key components - which files are most important, where to start reading, what depends on what
Detecting patterns - understanding architectural decisions and why code is structured a certain way
Highlighting issues like circular dependencies so students learn what to avoid in their own projects

Instead of having AI write code for you, Code Cartographer teaches you to read, understand, and learn from existing code - a crucial skill for any developer.

How I built it

I built Code Cartographer using:

Python for the core analysis engine with tree-sitter for reliable code parsing
Google Gemini 2.5 Flash for AI-powered explanations that teach rather than just generate
Flask + WebSocket for a real-time web dashboard that makes learning interactive
NetworkX + Plotly for visual dependency graphs that help students see connections
TypeScript for VS Code extension so students can learn right in their IDE

The architecture is modular and educational - students can even explore Code Cartographer's own codebase to learn how it works!

Challenges I ran into

Making AI explanatory, not generative: Crafting prompts that make Gemini explain and teach rather than just summarize
Balancing detail and clarity: Providing enough information to be educational without overwhelming beginners
Visual learning: Creating intuitive graphs that help visual learners understand code relationships
Performance for learning: Making analysis fast enough that students can explore freely without waiting
Real-world applicability: Ensuring it works on actual open-source projects students want to learn from

Accomplishments that I'm proud of

Created a tool that promotes understanding over automation - teaching students to fish rather than giving them fish
Made AI accessible for learning rather than just code generation
Built something that works on real projects - students can analyze React, Flask, or any codebase they're learning
Designed an intuitive interface that makes complex dependency graphs understandable for beginners
Demonstrated that AI can be used responsibly in education - to enhance learning, not replace it

What I learned

The difference between AI that does work FOR you vs AI that helps you UNDERSTAND
How to design educational tools that promote active learning
The importance of visualization in understanding complex systems
How to integrate multiple AI and analysis technologies into a cohesive learning tool
That the best use of AI in education is teaching students to think critically, not replacing their thinking

What's next for Code Cartographer

Learning paths: Suggest which files to read first based on learning goals
Concept extraction: Identify and explain programming patterns and best practices found in the code
Quiz generation: Create comprehension questions based on the analyzed code
Comparison mode: Compare different implementations to teach design decisions
Classroom integration: Features for professors to use in teaching software architecture
Study groups: Collaborative features where students can share insights and annotations