--- title: CodeAtlas emoji: πŸ—οΈ colorFrom: blue colorTo: purple sdk: gradio sdk_version: "6.0.1" app_file: app.py pinned: false license: mit tags: - mcp-in-action-track-consumer - mcp - gradio - llamaindex - gemini - elevenlabs - modal - openai - agents - code-visualization - fastmcp - graphviz - architecture - visualization - mcp-server - mcp-in-action-track-consumer - mcp-in-action-track-enterprise - building-mcp-track-consumer - building-mcp-track-enterprise ---
# πŸ—οΈ CodeAtlas ### AI-Powered Codebase Visualization & Understanding **Transform any GitHub repository into beautiful architecture diagrams with voice narration and AI chat β€” powered by MCP** [![Live Demo](https://img.shields.io/badge/πŸš€_Live_Demo-HuggingFace-yellow)](https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas) [![Gradio](https://img.shields.io/badge/Built%20with-Gradio-FF7C00)](https://gradio.app) [![MCP](https://img.shields.io/badge/MCP-Server%20Enabled-8B5CF6)](https://modelcontextprotocol.io) [![LlamaIndex](https://img.shields.io/badge/πŸ¦™_LlamaIndex-Integrated-blue)](https://llamaindex.ai) [![Gemini](https://img.shields.io/badge/✨_Gemini_3.0-Powered-4285F4)](https://ai.google.dev) [![OpenAI](https://img.shields.io/badge/πŸ€–_GPT--5.1-Supported-412991)](https://openai.com) [![ElevenLabs](https://img.shields.io/badge/πŸŽ™οΈ_ElevenLabs-Voice-000000)](https://elevenlabs.io) [![Modal](https://img.shields.io/badge/☁️_Modal-Deployed-00D4AA)](https://modal.com) **[πŸ”— Try it Live](https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas)** β€’ **[πŸ“Ί Demo Video](#-demo-video)** β€’ **[πŸ“± Twitter Post](https://x.com/aghilsabu/status/1995249175336997350?s=20)** β€’ **[πŸ’Ό LinkedIn Post](https://www.linkedin.com/posts/aghilsabu_codeatlas-ai-powered-codebase-visualization-share-7401015482310393857-vHRg)**
--- ## 🎬 Demo Video [![CodeAtlas Demo](https://img.youtube.com/vi/J8dcTLzNgpE/maxresdefault.jpg)](https://youtu.be/J8dcTLzNgpE) **[▢️ Watch on YouTube](https://youtu.be/J8dcTLzNgpE)** > *Watch CodeAtlas analyze a GitHub repository in real-time, generate architecture diagrams, and explain the codebase with voice narration.* --- ## 🌟 What is CodeAtlas? **CodeAtlas** is your AI-powered codebase companion that instantly visualizes and explains any software architecture. Simply paste a GitHub URL, and within seconds get: - πŸ—ΊοΈ **Beautiful Architecture Diagrams** β€” AI-generated Graphviz visualizations showing components, layers, and relationships - πŸ”Š **Voice Narration** β€” Listen to AI explain your codebase architecture (powered by ElevenLabs) - πŸ’¬ **AI Chat** β€” Ask questions and get intelligent answers about the code - πŸ€– **MCP Integration** β€” Use with Claude Desktop, Cursor, or any MCP-compatible client **Perfect for:** Code reviews, onboarding new developers, documentation, learning new frameworks, and understanding legacy codebases. --- ## ✨ Key Features | Feature | Description | Technology | |---------|-------------|------------| | πŸ”— **GitHub Analysis** | Paste any public repo URL and analyze instantly | GitHub API + Smart Filtering | | πŸ“ **ZIP Upload** | Upload local codebases for private analysis | File Processing | | πŸ—ΊοΈ **Architecture Diagrams** | AI-generated Graphviz diagrams with layers, clusters, and relationships | **Graphviz** + Gemini AI | | πŸ”Š **Voice Narration** | Natural speech explanation of your architecture | **πŸŽ™οΈ ElevenLabs TTS** | | πŸ’¬ **AI Chat** | Context-aware Q&A about your codebase | **πŸ¦™ LlamaIndex** RAG | | πŸ€– **Multi-Model Support** | Choose between Gemini 3.0/2.5 Pro/Flash or GPT-5.1/5 Mini | **Google Gemini** + **OpenAI** | | πŸ“ **Interactive Layout** | Real-time diagram adjustments (direction, spacing, zoom) | Graphviz DOT | | πŸ“œ **Diagram History** | Browse and reload previous analyses | Local Storage | | πŸ”Œ **MCP Server** | 4 tools for AI agent integration | **FastMCP** | | ☁️ **Cloud Ready** | One-command serverless deployment | **Modal** | --- ## πŸ”Œ MCP Server Integration CodeAtlas exposes **4 MCP tools** for AI agent integration: | Tool | Description | |------|-------------| | `analyze_codebase` | Generate architecture diagram from GitHub URL | | `get_architecture_summary` | Get text summary of codebase architecture | | `chat_with_codebase` | Ask questions about any codebase | | `list_recent_analyses` | List recently analyzed repositories | **MCP Endpoint:** `https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/gradio_api/mcp/sse` --- ## πŸ› οΈ Tech Stack CodeAtlas integrates multiple technologies for a comprehensive solution: | Layer | Technology | Purpose | |-------|------------|---------| | **🎨 UI Framework** | [**Gradio 6**](https://gradio.app) | Multi-page routing, `mcp_server=True` | | **πŸ¦™ AI Framework** | [**LlamaIndex**](https://llamaindex.ai) | Unified LLM interface, RAG | | **✨ Primary AI** | [**Google Gemini**](https://ai.google.dev) | Gemini 3.0 Pro, 2.5 Pro/Flash | | **πŸ€– Alternate AI** | [**OpenAI**](https://openai.com) | GPT-5.1, GPT-5 Mini/Nano | | **πŸŽ™οΈ Voice TTS** | [**ElevenLabs**](https://elevenlabs.io) | High-quality voice narration | | **☁️ Backend API** | [**Modal**](https://modal.com) | Serverless API endpoints | | **πŸ”Œ MCP Protocol** | [**FastMCP**](https://github.com/jlowin/fastmcp) | Model Context Protocol | --- ## πŸ“ Project Structure ``` codeAtlas/ β”œβ”€β”€ app.py # Main Gradio application entry point β”œβ”€β”€ modal_backend.py # Modal serverless API deployment β”œβ”€β”€ requirements.txt # Python dependencies β”œβ”€β”€ Makefile # Build and run commands β”œβ”€β”€ src/ β”‚ β”œβ”€β”€ config.py # Configuration management β”‚ β”œβ”€β”€ core/ β”‚ β”‚ β”œβ”€β”€ analyzer.py # AI-powered codebase analysis β”‚ β”‚ β”œβ”€β”€ diagram.py # Graphviz diagram generation β”‚ β”‚ └── repository.py # GitHub/ZIP repository loading β”‚ β”œβ”€β”€ integrations/ β”‚ β”‚ β”œβ”€β”€ elevenlabs.py # ElevenLabs TTS integration β”‚ β”‚ β”œβ”€β”€ modal_client.py # Modal API client β”‚ β”‚ └── voice.py # Voice synthesis utilities β”‚ β”œβ”€β”€ mcp/ β”‚ β”‚ β”œβ”€β”€ server.py # FastMCP server setup β”‚ β”‚ └── tools.py # MCP tool definitions β”‚ └── ui/ β”‚ β”œβ”€β”€ app.py # UI layout and routing β”‚ β”œβ”€β”€ components.py # Reusable UI components β”‚ └── styles.py # CSS styling β”œβ”€β”€ data/ β”‚ β”œβ”€β”€ diagrams/ # Generated diagram files β”‚ β”œβ”€β”€ audios/ # Voice narration files β”‚ └── logs/ # Application logs └── assets/ └── screenshots/ # Documentation screenshots ``` --- ## πŸš€ Quick Start ### Prerequisites - Python 3.10+ - Graphviz (`brew install graphviz` on macOS, `apt install graphviz` on Linux) ### Option 1: Run Locally ```bash # Clone and setup git clone https://github.com/aghilsabu/codeAtlas.git cd codeAtlas python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt # Run python app.py ``` Open http://localhost:7860 and go to **Settings** to add your API keys. ### Option 2: Use Makefile ```bash make install # Create venv and install dependencies make run # Run the application ``` ### Option 3: Deploy API Backend to Modal ```bash # Deploy the serverless API backend on Modal modal deploy modal_backend.py ``` **Modal Backend API Endpoints:** | Endpoint | URL | |----------|-----| | Health Check | `https://aghilsabu--codeatlas-backend-health.modal.run` | | Generate Diagram | `https://aghilsabu--codeatlas-backend-generate-diagram.modal.run` | | Generate Voice | `https://aghilsabu--codeatlas-backend-generate-voice.modal.run` | | Analyze Codebase | `https://aghilsabu--codeatlas-backend-analyze-codebase.modal.run` | These serverless endpoints handle heavy compute operations and can be called from any frontend! πŸš€ --- ## βš™οΈ Configuration Configure API keys via the **Settings** page in the UI: | Key | Required | Purpose | Get Key | |-----|----------|---------|---------| | **Gemini API Key** | βœ… Yes | Primary AI engine | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | | **OpenAI API Key** | Optional | GPT-5.1/5 Mini models | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | | **ElevenLabs API Key** | Optional | Voice narration | [elevenlabs.io/app/developers](https://elevenlabs.io/app/developers/api-keys) | --- ## πŸ” How It Works ```mermaid flowchart LR A[GitHub URL/ZIP] --> B[Repository Loader] B --> C[Smart File Filter] C --> D[LlamaIndex + Gemini] D --> E[DOT Diagram] E --> F[Graphviz Render] F --> G[Interactive Viewer] D --> H[Architecture Summary] H --> I[ElevenLabs TTS] I --> J[πŸ”Š Audio Player] D --> K[πŸ’¬ AI Chat] ``` 1. **πŸ“₯ Load Repository** β€” Download from GitHub or extract ZIP, smart-filter to relevant code files (excludes node_modules, tests, configs) 2. **🧠 AI Analysis** β€” LlamaIndex processes code context with Gemini 3.0 (or GPT-5.1) to understand architecture 3. **πŸ—ΊοΈ Generate Diagram** β€” AI creates Graphviz DOT code with 15-20 key nodes showing layers, clusters, and relationships 4. **πŸ”Š Voice Narration** β€” AI generates natural summary, ElevenLabs converts to high-quality speech 5. **πŸ’¬ Chat Interface** β€” Context-aware Q&A about the analyzed codebase with conversation history --- ## 🎯 Use Cases - **Onboarding** β€” New team members instantly understand codebase structure - **Documentation** β€” Generate architecture diagrams for README/docs - **Code Review** β€” Visualize changes in context of overall architecture - **Learning** β€” Understand how popular open-source projects are structured - **Legacy Code** β€” Make sense of undocumented older codebases --- ## πŸ‘¨β€πŸ’» Author **Aghil Sabu** - GitHub: [@aghilsabu](https://github.com/aghilsabu) - HuggingFace: [@aghilsabu](https://huggingface.co/aghilsabu) - Twitter/X: [@AghilSabu](https://x.com/AghilSabu) --- ## πŸ“œ License MIT License β€” see [LICENSE](LICENSE) for details. ---
**Built with ❀️ for MCP's 1st Birthday Hackathon πŸŽ‚** *November 2025* [![Star on GitHub](https://img.shields.io/github/stars/aghilsabu/codeAtlas?style=social)](https://github.com/aghilsabu/codeAtlas)