🗺️ MapMyRepo

Transform Your Codebase into an Interactive Knowledge Graph

MapMyRepo is a powerful AI-powered visualization tool that transforms any GitHub repository or local codebase into an interactive, navigable node graph. Perfect for understanding complex architectures, onboarding new developers, or exploring unfamiliar codebases.

Features • Demo • Installation • Usage • Tech Stack

---

✨ Features

🎨 Interactive Graph Visualization

• Force-Directed Layout: Files and folders represented as interconnected nodes using D3.js
• Smooth Navigation: Zoom, pan, and drag nodes to explore your codebase intuitively
• Visual Hierarchy: Distinct icons and colors for folders, files, and different file types
• Node Expansion: Double-click folders to expand/collapse their contents dynamically

🤖 AI-Powered Intelligence (Google Gemini)

• Smart Summaries: Automatically generates architectural overviews for folders and files
• Code Analysis: Explains the purpose, exports, and key functionality of individual files
• Contextual Q&A: Ask questions about your codebase and get intelligent, context-aware answers
• Real-time Insights: Chat interface integrated directly into the node selection panel

📥 Flexible Import Options

• Local Upload: Drag and drop folders directly from your file system
• GitHub Integration: Paste any public GitHub repository URL to visualize instantly
• Smart Parsing: Automatically filters out node_modules, .git, and other build artifacts

🌗 Modern UI/UX

• Dark/Light Mode: Fully themed interface that adapts to your preference
• Glassmorphism Design: Sleek, modern sidebar with backdrop blur effects
• Responsive Layout: Works seamlessly on desktop and tablet devices
• Animated Backgrounds: Dynamic particle effects and grid animations

---

🎬 Demo

Try visualizing any public repository:

https://github.com/facebook/react
https://github.com/microsoft/vscode
https://github.com/vercel/next.js

---

🚀 Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher) - Download here
• npm or yarn package manager
• Git - Download here
• Google Gemini API Key - Get one free

Step 1: Clone the Repository

git clone https://github.com/vasu-devs/MapMyRepo.git
cd MapMyRepo

Step 2: Install Dependencies

Using npm:

npm install

Or using yarn:

yarn install

Step 3: Configure Environment Variables

Create a .env.local file in the root directory:

# For Windows
copy .env.example .env.local

# For macOS/Linux
cp .env.example .env.local

Then add your API keys to .env.local:

# Google Gemini AI API Key (Required)
VITE_GEMINI_API_KEY=your_gemini_api_key_here

# GitHub Personal Access Token (Optional - for private repos and higher rate limits)
VITE_GITHUB_TOKEN=your_github_token_here

🔑 Getting Your API Keys:

• Gemini API Key: Visit Google AI Studio, sign in, and click "Create API Key"
• GitHub Token (Optional): Go to GitHub Settings > Developer settings > Personal access tokens and generate a new token with repo scope

Step 4: Run the Development Server

npm run dev

The application will start at http://localhost:5173 (Vite's default port).

Step 5: Build for Production (Optional)

npm run build

The optimized build will be created in the dist folder.

To preview the production build locally:

npm run preview

---

📖 Usage Guide

1️⃣ Visualize a Repository

Option A: Upload a Local Folder

1. Click the upload zone or drag and drop a folder from your file system
2. MapMyRepo will parse the directory structure (excludes node_modules, .git, etc.)
3. The graph will render automatically

Option B: Load from GitHub

1. Paste a full GitHub repository URL into the input field:

   https://github.com/username/repository
   

2. Press Enter or click the arrow button
3. The repository will be fetched and visualized

2️⃣ Navigate the Graph

Action	Effect
Scroll	Zoom in/out
Click + Drag	Pan across the canvas
Click Node	Select node and open sidebar
Double-Click Folder	Expand/collapse folder contents
Hover Node	Highlight connected nodes

3️⃣ Explore with AI

Once you select a node:

• Details Tab: View file/folder metadata and AI-generated architectural summary
• Discussion Tab: Ask questions like:
  • "What does this file do?"
  • "Where is authentication handled?"
  • "Explain the routing structure"
  • "What are the main exports of this module?"

4️⃣ Switch Themes

Click the theme toggle button (☀️/🌙) in the top-right corner to switch between light and dark modes.

---

🛠️ Tech Stack

Technology	Purpose
React 19	UI framework with modern hooks
TypeScript	Type-safe JavaScript
Vite	Lightning-fast build tool
D3.js	Force-directed graph visualization
Tailwind CSS	Utility-first styling
Google Gemini AI	Code analysis and Q&A
Marked	Markdown rendering for AI responses
JetBrains Mono	Developer-friendly monospace font

---

📂 Project Structure

MapMyRepo/
├── components/
│   ├── FileUploader.tsx       # Landing page & upload logic
│   ├── RepoVisualizer.tsx     # D3.js graph visualization
│   ├── Sidebar.tsx            # Node details & AI chat panel
│   └── SearchBar.tsx          # (Future) Search functionality
├── services/
│   ├── fileService.ts         # File parsing & GitHub API integration
│   └── geminiService.ts       # Google Gemini AI integration
├── public/
│   ├── favicon.svg            # App favicon
│   └── ...
├── App.tsx                    # Main application layout
├── index.tsx                  # React entry point
├── types.ts                   # TypeScript type definitions
├── vite.config.ts             # Vite configuration
├── tsconfig.json              # TypeScript configuration
└── package.json               # Project dependencies

---

🔧 Configuration

Vite Configuration

The project uses Vite with React plugin. Key configurations in vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
  },
  build: {
    outDir: 'dist',
  },
})

GitHub API Configuration

For private repositories or to avoid rate limits, configure a GitHub Personal Access Token:

1. Generate a token at github.com/settings/tokens
2. Select repo scope for private repositories
3. Add to .env.local: VITE_GITHUB_TOKEN=your_token_here

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

How to Contribute

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/MapMyRepo.git

3. Create a branch:

   git checkout -b feature/amazing-feature

4. Make your changes and commit:

   git commit -m "Add amazing feature"

5. Push to your fork:

   git push origin feature/amazing-feature

6. Open a Pull Request

Development Guidelines

• Follow the existing code style (TypeScript, React Hooks)
• Add TypeScript types for all new code
• Test your changes thoroughly
• Update documentation as needed

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Google Gemini AI for powerful code analysis capabilities
• D3.js community for excellent graph visualization tools
• React and Vite teams for modern web development tools

---

👤 Author

Vasudev Siddharth

• GitHub: @vasu-devs
• Twitter/X: @Vasu_Devs
• Portfolio: [Coming Soon]

---

🐛 Troubleshooting

Graph doesn't render

• Ensure your repository has valid file structure
• Check browser console for errors
• Try clearing browser cache and reloading

AI features not working

• Verify VITE_GEMINI_API_KEY is correctly set in .env.local
• Check that the API key is valid at Google AI Studio
• Ensure you have an active internet connection

GitHub repository fetch fails

• Ensure the repository URL is correct and public
• For private repos, add VITE_GITHUB_TOKEN to .env.local
• Check if you've hit GitHub API rate limits (60 requests/hour without token)

Application won't start

• Delete node_modules and reinstall: rm -rf node_modules && npm install
• Ensure you're using Node.js v18 or higher: node --version
• Check for port conflicts on 5173

---

📊 Roadmap

• Add search functionality to find specific files/folders
• Export graph as image (PNG/SVG)
• Support for private GitHub repositories
• Dependency graph visualization for imports/exports
• Code metrics and statistics dashboard
• Multi-repository comparison view
• VSCode extension integration

---

💖 Support

If you find MapMyRepo useful, please consider:

• ⭐ Starring this repository
• 🐦 Sharing on Twitter/X
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features

---

⬆ Back to Top

Made with ❤️ and ☕ by Vasu-Devs