GoMindMapper

🚀 Advanced Go Function Relationship Visualizer 🚀

Interactive function relationship visualization for Go codebases with intelligent type resolution, interface implementation detection, and external module analysis. Scan any Go repository and explore it through an expandable, pannable, zoomable mind map.

Go (AST Analyzer + HTTP API) + React (Interactive Mind Map) + Notion‑style UI

---

📋 Table of Contents

1. 🚀 Quick Start
2. ✨ Features Overview
3. 🏗️ Architecture
4. ⚙️ Installation & Setup
5. 🔧 Development
6. 📖 Usage Guide
7. 🎯 Advanced Features
8. 🔍 API Reference
9. 📊 Data Models
10. 🎨 Customization
11. 🗺️ Roadmap
12. 🤝 Contributing
13. 📄 License

---

🚀 Quick Start

Get started with GoMindMapper in under 2 minutes:

Single Command Deployment

# Clone and run (example analyzing the 'gopdfsuit' subdirectory)
git clone https://github.com/chinmay-sawant/gomindmapper.git
cd gomindmapper
go run cmd/server/main.go -path gopdfsuit -addr :8080 --include-external=true --skip-folders="golang.org,gin-gonic,bytedance,ugorji,go-playground"

Command Flags: - -path <dir>: Repository/subfolder to analyze (e.g., gopdfsuit) - -addr <addr>: HTTP server address (default :8080) - --include-external: Include external module functions in analysis - --skip-folders: Comma-separated dependency prefixes to skip during external scanning

Access Points: - 🌐 Overview: http://localhost:8080/gomindmapper/ - 🗺️ Mind Map: http://localhost:8080/gomindmapper/view/

Note: Production React assets are automatically served by the Go server — no separate frontend setup required!

Makefile Shortcuts

make ui-build   # Build React frontend
make server     # Start Go server
make ui         # Start React dev server
make run        # Run CLI analyzer

---

✨ Features Overview

GoMindMapper goes beyond simple function visualization with advanced Go code analysis capabilities:

🎯 Core Analysis Engine

• 🧠 AST-based Go Analysis - Uses Go's built-in AST parsing for accurate function extraction
• 🔍 Smart Root Detection - Automatically identify top-level entry points (functions not called by any other user function)
• 🏗️ Interface Implementation Detection - Discover concrete implementations of interfaces and add them to call graphs
• 🔗 Type Resolution Engine - Resolve method calls through comprehensive type analysis
• 📦 External Module Scanning - Recursively scan external dependencies with intelligent filtering
• 🎛️ Advanced Filtering - Multi-layer filtering: stdlib, external libraries, framework noise, custom patterns
• ⚡ Performance Optimization - Parallel processing, in-memory caching, and efficient data structures

🎨 Interactive UI & Visualization

• 🗺️ Google NotebookLLM-inspired Nodes - Custom-designed function nodes with color-coded types (main, handler, middleware, config, router)
• 🖱️ Intuitive Controls - Pan (drag background), zoom (mouse wheel), expand/collapse nodes individually
• 🌓 Advanced Theming - Dark/light theme with system preference detection and localStorage persistence
• 📤 Drag & Drop Upload - Drop JSON files directly onto interface for offline analysis
• 🔎 Real-time Search - Debounced search with instant results and pagination
• 📋 Function Details Panel - Comprehensive information display on node selection (file path, line numbers, calls)
• 📱 Responsive Design - Works seamlessly across desktop, tablet, and mobile devices
• 🎞️ Screenshot Slideshow - Interactive feature showcase with auto-play and navigation
• 📊 Comparison Table - Built-in comparison with other Go visualization tools

🔧 Data Management & Integration

• 🔄 Dual Data Modes - Switch between offline JSON snapshots or live server API
• 🔥 Hot Reload Capability - Refresh data from repository without restarting (POST /api/reload)
• 💾 Multi-format Export - Download as JSON, with planned support for GraphML/DOT/SVG
• 📊 Multiple Output Formats - Generate functions.json, functionmap.json, and removed_calls.json
• 🌐 Live Server Integration - RESTful API with pagination, search, and real-time updates
• 🔒 Concurrent Safety - Thread-safe operations with proper mutex handling

---

🏗️ Architecture

GoMindMapper follows a modern 3-tier architecture with intelligent caching and real-time capabilities:

┌────────────────────────────┐    JSON Artifacts    ┌──────────────────────────────┐
│ 🔍 Go Analyzer (CLI)        │ ──────────────────▶ │ 📄 functionmap.json         │
│ • AST Parsing               │                      │ 📄 functions.json           │
│ • Type Resolution           │                      │ 📄 removed_calls.json       │
│ • Interface Detection       │                      └─────────┬────────────────────┘
│ • External Module Scanning  │                                │
└──────────┬─────────────────┘                                │ Consumed by
           │ In-process Reuse                                   ▼
           ▼                                   ┌──────────────────────────────┐
┌────────────────────────────┐   REST API + WebSockets   │ ⚛️ React Mind Map UI         │
│ 🌐 Go HTTP Server           │ ◀────────────────────────▶ │ • Interactive Visualization  │
│ • RESTful API               │                             │ • Theme Management          │
│ • Real-time Updates         │                             │ • Search & Filter           │
│ • Pagination Engine         │                             │ • Drag & Drop               │
│ • Concurrent Safety         │                             │ • Responsive Design         │
│ • Static Asset Serving      │                             └──────────────────────────────┘
└────────────────────────────┘                             

Key Components:

• 📁 cmd/main.go - CLI analyzer with interface detection and type resolution
• 📁 cmd/server/main.go - HTTP server with in-memory caching and parallel processing
• 📁 cmd/analyzer/* - Core analysis engine (types, relations, utils, external modules)
• 📁 mind-map-react/ - Vite+React SPA with advanced UI components
• 📁 docs/ - Production build output served by Go server

⚙️ Installation & Setup

Prerequisites

• Go 1.23 - Download Go
• Node.js 16+ & npm - Download Node.js (only for development)
• Git - Download Git

Installation Options

Option 1: Direct Git Clone (Recommended)

# Clone the repository
git clone https://github.com/chinmay-sawant/gomindmapper.git
cd gomindmapper

# Run immediately (production-ready)
go run cmd/server/main.go -path . -addr :8080

Option 2: Go Install (Coming Soon)

# Future release
go install github.com/chinmay-sawant/gomindmapper@latest
gomindmapper --help

Build from Source

# Clone and build
git clone https://github.com/chinmay-sawant/gomindmapper.git
cd gomindmapper

# Build frontend (optional - for latest UI changes)
cd mind-map-react
npm install && npm run build
cd ..

# Build Go binary
go build -o gomindmapper cmd/server/main.go

# Run
./gomindmapper -path /path/to/your/go/project -addr :8080

---

🔧 Development

Development Environment Setup

# 1. Clone repository
git clone https://github.com/chinmay-sawant/gomindmapper.git
cd gomindmapper

# 2. Start backend server
go run cmd/server/main.go -path . -addr :8080

# 3. In another terminal, start frontend dev server
cd mind-map-react
npm install
npm run dev

# 4. Access development UI
# Frontend dev server: http://localhost:5173/gomindmapper/view
# Backend API: http://localhost:8080/api/relations

Development Workflow

• Backend changes: Restart go run cmd/server/main.go
• Frontend changes: Auto-reload via Vite dev server
• Build for production: make ui-build then make server

Project Structure

gomindmapper/
├── 📁 cmd/                    # Go applications
│   ├── 📄 main.go             # CLI analyzer
│   ├── 📁 analyzer/           # Core analysis engine
│   │   ├── 📄 types.go        # Data structures
│   │   ├── 📄 relations.go    # Relationship building
│   │   ├── 📄 utils.go        # Function call extraction
│   │   ├── 📄 types_resolver.go # Type resolution & interface detection
│   │   └── 📄 external.go     # External module scanning
│   └── 📁 server/
│       └── 📄 main.go          # HTTP server
├── 📁 mind-map-react/         # React frontend
│   ├── 📄 vite.config.js      # Build config (outputs to ../docs)
│   ├── 📄 package.json        # Dependencies
│   └── 📁 src/
│       ├── 📄 App.jsx          # Main app component
│       ├── 📁 components/      # UI components
│       └── 📁 contexts/        # Theme management
├── 📁 docs/                   # Production build output
├── 📄 makefile               # Development shortcuts
└── 📄 README.md              # This file

---

📖 Usage Guide

CLI Analyzer Mode

Generate JSON artifacts for offline analysis:

# Basic analysis (user functions only)
go run cmd/main.go -path . --include-external=false

# Advanced analysis (includes external dependencies)
go run cmd/main.go -path . --include-external=true --skip-folders="golang.org,google.golang.org"

# Analyze specific project
go run cmd/main.go -path /path/to/your/go/project --include-external=true

Generated Files: | File | Purpose | Content | |------|---------|--------| | functions.json | Raw function data | All discovered functions + unfiltered calls | | functionmap.json | Filtered relationships | User→user function relationships only | | removed_calls.json | Diagnostics | Calls filtered out during analysis |

Server Mode (Recommended)

Start the HTTP server with live analysis and web UI:

# Basic server
go run cmd/server/main.go -path . -addr :8080

# Advanced with external libraries
go run cmd/server/main.go -path . -addr :8080 --include-external=true --skip-folders="golang.org,gin-gonic"

# Analyze external project
go run cmd/server/main.go -path /path/to/project -addr :8080

Access Points: - 🌐 Overview: http://localhost:8080/gomindmapper/ - 🗺️ Mind Map: http://localhost:8080/gomindmapper/view/ - 📡 API Docs: http://localhost:8080/api/relations

Command Line Options

Flag	Description	Default	Example
-path <dir>	Repository to analyze	. (current)	-path ./myproject
-addr <address>	Server listen address	:8080	-addr :3000
--include-external	Include external modules	false	--include-external=true
--skip-folders <patterns>	Skip dependency patterns	""	--skip-folders="golang.org,gin-gonic"

---

🎯 Advanced Features

GoMindMapper includes several advanced features that set it apart from other Go visualization tools:

🧠 Interface Implementation Detection

Automatically discovers concrete implementations of interfaces and includes them in the call graph:

// Example: Interface definition
type UserService interface {
    CreateUser(user User) error
    GetUser(id string) (*User, error)
}

// Implementation detection finds:
type DatabaseUserService struct { /* ... */ }
func (d *DatabaseUserService) CreateUser(user User) error { /* ... */ }
func (d *DatabaseUserService) GetUser(id string) (*User, error) { /* ... */ }

Benefits: - 🎯 Precise Call Resolution: Method calls resolve to actual implementations - 🔗 Complete Dependency Trees: See full call chains through interface boundaries - 📊 Better Visualization: Understand polymorphic relationships in your code

🔍 Advanced Type Resolution Engine

Intelligent type resolution handles complex Go patterns:

• Struct Field Method Calls: svc.UserService.CreateUser() → DatabaseUserService.CreateUser
• Import Alias Resolution: Resolves through import aliases and package names
• External Type Mapping: Maps external types to their actual implementations
• Recursive Method Discovery: Finds methods called within implementations

📦 External Module Intelligence

Comprehensive external dependency analysis:

# Scans all go.mod files recursively
# Filters by relevance (only modules actually called)
# Applies intelligent skip patterns
go run cmd/server/main.go --include-external=true --skip-folders="golang.org,google.golang.org"

Features: - 🔄 Recursive go.mod Discovery: Finds all modules in monorepos - 🎛️ Smart Filtering: Only scans modules actually used by your code - ⚡ Performance Optimized: Parallel processing with timeout protection - 🎯 Relevance Scoring: Prioritizes frequently-used external functions

⚡ Performance Optimizations

• Parallel Processing: Multi-core function analysis and relation building
• In-Memory Caching: Fast access to parsed relationships
• Lazy Loading: Load function details on-demand
• Efficient Data Structures: Optimized for large codebases
• Memory Management: Automatic garbage collection and memory monitoring

🎨 Advanced UI Components

• Screenshot Slideshow: Interactive