CodeMap AI - Helping My Friend Understand Unfamiliar Codebases

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend What I Built When developers join an unfamiliar project, one of the first challenges is understanding how everything fits together. You open the repository and see something like: frontend/ backend/ components/ services/ routes/ controllers/ database/ utils/ Then the real questions begin: - Where does the application start? - Which component calls this API? - How does data flow from the frontend to the database? - What files are responsible for authentication? - If I change this file, what else could be affected? I built CodeMap AI for a friend who was struggling with exactly this problem. Instead of making them manually explore an unfamiliar repository, CodeMap AI analyzes the project and turns its structure and relationships into an interactive visual codebase map. I had my friend try CodeMap AI on an unfamiliar project to see whether the visual map and AI explanations actually made the codebase easier to understand. Using the visual map made it easier for him to understand how the different parts of the project are connected. Instead of opening files one by one, the overall structure could be understood first, followed by the AI explanation for specific parts of the code. How it works: The user provides a project/repository: GitHub Repository ↓ CodeMap AI ↓ Code Analysis ↓ Dependency & Relationship Detection ↓ Interactive Codebase Map ↓ AI-powered explanations The resulting map lets the user visually explore relationships between different parts of the application. Demo Youtube video: Code GitHub Repository: Samar-365 / CodeMap CodeMap AI is an AI-powered application that helps developers understand unfamiliar software projects by automatically analyzing a codebase and generating an interactive visual map of its architecture, components, dependencies, and data flow. CodeMap AI An AI-powered visual codebase navigator for understanding unfamiliar projects. Problem Joining a new engineering team, jumping into an open-source project, or inheriting legacy code often feels overwhelming: - Spaghetti Dependencies: Developers spend hours or days manually following imports, function definitions, and API calls across dozens of folders. - Outdated Documentation: Architecture diagrams in READMEs or wikis are frequently stale, incomplete, or missing entirely. - Fear of Breaking Changes: Modifying a utility, route, or model is risky when you cannot clearly visualize all downstream consumers. - Privacy and IP Concerns: Sending proprietary codebases to third-party cloud LLMs violates corporate NDAs, security compliance policies, and incurs recurring API costs. Solution CodeMap AI transforms complex, unfamiliar repositories into an interactive, multi-tier architectural map and provides a context-grounded local AI assistant: - Automatic Multi-Tier Layout: Categorizes files into clean architectural layers (Frontend UI, API Endpoints, Services, Data… How I Built It CodeMap AI combines open-weight AI, local semantic search, and code analysis into one pipeline: Local LLM via Ollama I use Ollama to run open-weight models entirely on the user's machine. The default model is Gemma 2 (2B) - small enough to run on a laptop CPU, but capable enough to produce clear architectural explanations. You can swap it for qwen3:4b, llama3.2, or phi4-mini depending on your hardware, all via an environment variable. No API key, no subscription, no cost.Semantic Embeddings via SentenceTransformers Every code chunk is embedded using all-MiniLM-L6-v2 - a lightweight, locally-run embedding model from Hugging Face. These embeddings are indexed in FAISS for sub-millisecond vector search. When you ask a question, the RAG pipeline retrieves the most semantically relevant code chunks from your repository and injects them directly into the LLM's prompt context, making every answer grounded in your actual codebase.Multi-language Code Analysis The backend performs multi-language code analysis across Python, JavaScript, TypeScript, JSX/TSX, Java, JSON, YAML, and SQL files using Python's nativeast module for Python code and custom tokenization/parsing logic for other supported file types. It extracts: Imports and dependencies Class and function definitions API route handlers (@app.get, Express routes, etc.) Frontend network calls (fetch, axios) Database schema definitions These are then resolved into a directed dependency graph that feeds both the React Flow visualization and the RAG retrieval pipeline. Tech Stack: - Frontend: React 18 + Vite + React Flow (Dagre) - Backend: Python 3.11 + FastAPI + Uvicorn - AST Parsing: Python ast module + regex tokenizers - Vector Search: FAISS + sentence-transformers - Embeddings: all-MiniLM-L6-v2 (local, free) - Local LLM: Ollama - qwen3:4b, gemma2:2b, llama3.2 - Graph Layout: Dagre (hierarchical DAG algorithm) Why Does Open Innovation Matter? One of the most important aspects of CodeMap AI is that the application deals with source code. A developer may want to understand a private project, a college project, or an internal codebase. Sending an entire repository to a closed AI service isn't always desirable. Using open-source/open-weight AI gives the project more flexibility around how the AI is run and where the source code is processed. For CodeMap AI, this means the system can be designed around: - Open-weight models - Local inference - Self-hosted AI - Replaceable models - Greater control over source-code processing The goal isn't simply to add AI to a developer tool. The goal is to make AI-based codebase understanding possible while giving developers more control over the models and infrastructure involved. In my implementation, the AI inference can run locally, meaning the source code doesn't have to be sent to a closed third-party AI provider for analysis. Prize Categories Gemma - Best Use of Gemma I used Gemma, Google's open-weight model, as a core part of CodeMap AI's codebase understanding and AI-powered explanation system. ElevenLabs - Best Use of ElevenLabs I used ElevenLabs to generate the voice-over narration for my CodeMap AI demo video. The voice-over walks through the problem CodeMap AI solves, demonstrates the application's workflow, and explains how the visual codebase map and AI-powered analysis work. Top comments (0)