Turn dense, complex GitHub repositories into explorable 2D spatial maps. Zoom effortlessly from macro system architecture down to inline AST function calls with zero configuration.
Navigate huge codebases visually with auto-generated dependency graphs.
Human working memory holds only ~7 items at a time. Tracing code logic across dozens of disconnected IDE tabs forces continuous cognitive re-indexing, spatial disorientation, and mental fatigue.
Human spatial memory recalls physical coordinates and visual structures instinctively. RepoMap parses your repository's Abstract Syntax Tree (AST), extracts exact module dependencies and function definitions, and pins them onto a persistent, deterministic 2D grid.
Onboard in hours instead of weeks. Inspect live function call chains, trace execution pipelines, query multi-agent AI assistants, and export presentation-ready diagrams side-by-side without ever leaving your visual context.
- 🎯 AST-Verified Spatial Knowledge Graph: Automatically parses AST imports, exports, and call hierarchies to generate an interactive, drag-and-zoom 2D node map.
- 🖼️ High-Density Cardless Editorial UI: Designed with modern monochrome typography, sleek glassmorphic aesthetics, and dynamic scroll animations for maximum spatial clarity.
- 🤖 Multi-Agent AI Architectural Assistant: Deeply integrated with Google Gemini 2.5 Flash (and fallback Llama 3 via Groq) to generate instant high-level summaries, explain complex functions, and answer architectural questions.
- 🔍 Split-Screen Code & Call Tracing: Click any node or function to inspect source code, verify callers/callees (
[Entry] ──► [Auth] ──► [DB]), and explore the module connections. - ⚡ Instant 0-Second Setup: Paste any public GitHub repository link (
owner/repositoryor full URL) with zero backend indexing or manifest files required. - 📊 Draw.io XML Export: Export clean, presentation-ready architectural blueprints directly from your browser to Draw.io (
.drawio/ XML). - 💾 Offline Smart Caching: Repository topologies, parsed AST graphs, and opened files are cached locally inside
IndexedDBfor lightning-fast re-navigation.
| Persona | Primary Goal | How RepoMap Supercharges Workflow |
|---|---|---|
| Onboarding Engineers & New Hires | Fast-Track Mastery | Understand system architecture and module relationships in hours instead of spending weeks lost in directory trees. |
| Staff Architects & Tech Leads | System Audit & Blueprints | Map dependency layers, identify circular references, and export Draw.io presentation diagrams. |
| Full-Stack & Systems Developers | Live Call Chain Tracing | Trace request pipelines right from API endpoints down to database models using the interactive spatial map. |
| Security Analysts & Code Reviewers | Data Flow Inspection | Rapidly follow user input sources and sensitive data flows across disconnected modules with zero context switching. |
- Core Framework: Next.js 15 / React 19 (
App Router) - Graph Visualization: React Flow (with custom AST node types & layout algorithms)
- Styling & Animation: Tailwind CSS v4, Lucide Icons, and Intersection Observers (
ScrollReveal) - Client Caching: IndexedDB (via
idb) for persistence - Syntax & Markdown:
react-syntax-highlighter,react-markdown
- Core Server: Node.js & Express (TypeScript)
- Git Engine:
simple-gitfor real-time repository cloning - AST Parsing Engine: Custom multi-language AST and regex-based dependency mapping engine (
parser/) - AI Orchestration:
@google/genai(Gemini) with fallback togroq-sdk(Llama 3) for the Q&A and architectural explanations.
- Node.js (v18 or higher)
- npm, yarn, or pnpm
- An optional Google Gemini API Key or Groq API Key for AI Q&A and Flow Generation.
Open a terminal and navigate to the server directory:
cd server
npm install(Note: Installing the server dependencies will automatically trigger the parser/ setup scripts).
Configure Environment Variables:
Create a .env file inside the server/ directory:
cp .env.example .envAdd your API keys and port settings inside server/.env:
PORT=5001
GEMINI_API_KEY=your_gemini_api_key_here
GROQ_API_KEY=your_groq_api_key_here_as_fallbackStart the Backend Server:
npm run devOpen a new terminal window and navigate to the client directory:
cd client
npm installConfigure Environment Variables:
Create a .env file inside the client/ directory:
cp .env.example .envEnsure NEXT_PUBLIC_API_URL points to your running backend server:
NEXT_PUBLIC_API_URL=http://localhost:5001Start the Frontend Client:
npm run devThe application will be live at http://localhost:3000!
If you prefer using Docker, you can spin up the entire full-stack environment with a single command.
-
Create Root
.envFile: Create a.envfile in the root directory of the project to provide your API keys to the containers:GEMINI_API_KEY=your_gemini_api_key_here GROQ_API_KEY=your_groq_api_key_here_as_fallback
-
Start the Containers:
docker-compose up --build
-
Access the App: The frontend will be available at http://localhost:3000 and the backend API at
http://localhost:5001.
(To run the containers in the background, use docker-compose up -d --build. To stop them, run docker-compose down.)
RepoMap is designed to mimic the cognitive model of a seasoned architect exploring a new codebase. Here is how the system processes your repositories:
- Connect & Clone: Paste any public GitHub repository URL into the top search bar. The backend
simple-gitengine securely clones a shallow copy of the repository into temporary storage. - AST Parsing & Mapping: The core
parser/engine traverses the directory tree, reading file contents and constructing an Abstract Syntax Tree (AST) for supported languages. It maps exact function definitions, classes, and cross-file imports to build a comprehensive dependency graph. - Spatial Graph Generation: The parsed JSON map is streamed to the frontend, where
React Flowdynamically calculates node positions, grouping files by directory and generating bezier curve edges to represent dependencies. - Explore Spatially: Click and drag anywhere on the canvas to pan. Use the scroll wheel to smoothly zoom from a macro "bird's-eye" directory view down to individual, actionable file nodes.
- Inspect Source & AI Explain: Click any node to slide open the side inspection panel. From here, you can view the raw syntax-highlighted source code, verify callers and callees, or click Explain to have the AI agents break down complex logic in plain English.
- Export Blueprints: Click the export option in the top right to download a highly-structured
.drawioXML file, perfect for embedding in your own documentation or presentations.
RepoMap is open source and we welcome contributions! Please read our Contributing Guidelines and our Code of Conduct to get started.
This project is licensed under the MIT License.