📋 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:

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

🎯 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 feature showcase
• Comparison Table: Built-in comparison with other Go tools
• Theme Context: System preference detection with localStorage
• Responsive Grid: Adaptive layouts for all screen sizes
• GitHub Integration: Live star count and repository linking

🔍 API Reference

Complete REST API documentation for integration and automation:

Core Endpoints

GET /api/relations

Retrieve paginated function relationships with full dependency closure.

Parameters:

• page (int): Page number (1-based, default: 1)
• pageSize (int): Items per page (max: 200, default: 10)
• includeInternals (bool): Include internal analyzer functions

Response:

{
  "page": 1,
  "pageSize": 10,
  "totalRoots": 45,
  "roots": [/* root function objects */],
  "data": [/* complete dependency closure */],
  "loadedAt": "2024-01-15T10:30:00Z"
}

GET /api/search

Search functions by name with pagination.

Parameters:

• q (string): Search query (required)
• page (int): Page number (default: 1)
• pageSize (int): Results per page (default: 10)

Response:

{
  "query": "CreateUser",
  "page": 1,
  "totalResults": 3,
  "matchingFunctions": [/* matching functions */],
  "data": [/* dependency closure for matches */]
}

POST /api/reload

Trigger repository rescan without server restart.

Response:

{
  "status": "reloaded",
  "loadedAt": "2024-01-15T10:35:00Z"
}

GET /api/download

Download complete function relations as JSON.

Headers:

• Content-Type: application/json
• Content-Disposition: attachment; filename=function_relations.json

Static Routes

• / - Overview page (Notion-style landing)
• /gomindmapper/ - Base application route
• /gomindmapper/view - Mind map interface
• /gomindmapper/view/* - SPA routing fallbacks
• /docs/* - Static assets (CSS, JS, images)

Authentication & CORS

• CORS: Enabled for all origins (*)
• Authentication: Currently none (designed for local/internal use)
• Rate Limiting: None (add reverse proxy for production)

📊 Data Models

Understand the internal data structures for integration and customization:

Core Types

// FunctionInfo - Raw function data from AST parsing
type FunctionInfo struct {
    Name     string   // Fully qualified name (package.function)
    Line     int      // Line number in source file
    FilePath string   // Relative file path
    Calls    []string // Function calls made within this function
}

// OutRelation - Processed relationship for JSON output
type OutRelation struct {
    Name     string      `json:"name"`
    Line     int         `json:"line"`
    FilePath string      `json:"filePath"`
    Called   []OutCalled `json:"called,omitempty"`
}

// OutCalled - Called function reference
type OutCalled struct {
    Name     string `json:"name"`
    Line     int    `json:"line"`
    FilePath string `json:"filePath"`
}

Advanced Types (Type Resolution)

// TypeInfo - Comprehensive type information
type TypeInfo struct {
    Name        string
    Package     string
    IsInterface bool
    IsStruct    bool
    Fields      map[string]string // field name → type
    Methods     []string
    ImportPath  string // for external types
}

// InterfaceImplementation - Concrete interface implementation
type InterfaceImplementation struct {
    InterfaceName string
    StructName    string
    PackageName   string
    FilePath      string
    Methods       map[string]MethodImplementation
}

File Formats

functionmap.json Structure

[
  {
    "name": "main.main",
    "line": 10,
    "filePath": "main.go",
    "called": [
      {
        "name": "config.LoadConfig",
        "line": 25,
        "filePath": "internal/config/config.go"
      },
      {
        "name": "server.StartServer",
        "line": 45,
        "filePath": "internal/server/server.go"
      }
    ]
  }
]

functions.json Structure

[
  {
    "name": "main.main",
    "line": 10,
    "filePath": "main.go",
    "calls": ["config.LoadConfig", "server.StartServer", "log.Println"]
  }
]

🎨 Customization

Filtering & Analysis Customization

Modify analysis behavior by editing key files:

cmd/analyzer/utils.go - Call Extraction Rules

// Add custom exclusion patterns in FindCalls()
standardPackages := map[string]bool{
    "fmt":     true,
    "os":      true,
    // Add your exclusions here
    "mycorp.internal": true,
}

// Add custom regex exclusions
regexFunctions := map[string]bool{
    "FindAllSubmatch": true,
    // Add patterns to ignore
    "MyCustomPattern": true,
}

cmd/analyzer/relations.go - Relationship Building

// Modify BuildRelations() to change output format
// Add custom matching logic for external functions
// Implement whitelist/blacklist patterns

UI Theming & Styling

Theme Variables (mind-map-react/src/App.css)

:root {
  /* Customize color scheme */
  --bg-primary: #0f0f0f;
  --text-primary: #ffffff;
  --accent-color: #3b82f6;
  
  /* Add custom variables */
  --node-primary: #1e40af;
  --node-secondary: #059669;
}

Component Customization

• Node Styles: Modify mind-map-react/src/components/Node.jsx
• Theme Logic: Edit mind-map-react/src/contexts/ThemeContext.jsx
• Layout: Update mind-map-react/src/components/Overview.css

Adding New Features

1. New API Endpoint

// In cmd/server/main.go
router.GET("/api/metrics", handleMetrics)

func handleMetrics(c *gin.Context) {
    // Your custom endpoint logic
}

2. New UI Component

// In mind-map-react/src/components/
import React from 'react';

const MyComponent = () => {
    return (
        <div className="my-component">
            {/* Your component JSX */}
        </div>
    );
};

export default MyComponent;

Configuration Files

Create configuration files for advanced customization:

gomindmapper.json (Future)

{
  "analysis": {
    "excludePatterns": ["*_test.go", "vendor/*"],
    "includeExternalByDefault": false,
    "maxExternalDepth": 3
  },
  "server": {
    "defaultPort": 8080,
    "enableCORS": true,
    "maxPageSize": 200
  },
  "ui": {
    "defaultTheme": "dark",
    "enableAnimations": true,
    "nodeColors": {
      "main": "#3b82f6",
      "handler": "#059669"
    }
  }
}

🗺️ Roadmap

✅ Advanced Features Completed:

• Interface Implementation Detection - Automatic discovery of concrete interface implementations
• Advanced Type Resolution Engine - Complex type resolution with import alias handling
• External Module Intelligence - Recursive go.mod scanning with relevance filtering
• Performance Optimization - Parallel processing, in-memory caching, lazy loading
• Search API (/api/search) with pagination and dependency closure
• Advanced Theming - System preference detection with localStorage persistence
• Custom Node Design - Google NotebookLLM-inspired UI components
• Screenshot Slideshow - Interactive feature showcase with auto-navigation
• Comparison Table - Built-in comparison with other Go visualization tools
• Hot Reload (POST /api/reload) - Live repository rescanning
• Drag & Drop Upload - Offline JSON analysis capability
• Multi-format Export - JSON download with planned GraphML/DOT/SVG support

🔜 Next Major Features:

• Real-time Code Analysis - FS watcher for automatic updates as code changes
• Function Metrics Dashboard - Complexity, fan-in/fan-out, LOC, cyclomatic complexity
• Call Path Analysis - Trace execution paths between functions
• Performance Profiling Integration - Overlay runtime performance data
• Collaborative Features - Share and bookmark specific views
• VS Code Extension - Inline function relationship viewer

🔮 Advanced Roadmap:

• AI-Powered Analysis - Semantic understanding of function purposes
• Architecture Pattern Detection - Identify common patterns (MVC, hexagonal, etc.)
• Microservices Visualization - Cross-service dependency mapping
• Security Analysis - Data flow analysis for security vulnerabilities
• Configuration Management - Project-specific analysis profiles
• Plugin System - Custom analyzers and visualizers
• Graph Database Integration - Neo4j backend for complex queries
• Export Formats - Mermaid, PlantUML, GraphML, GEXF support

🐳 Infrastructure & Distribution:

• Docker Images - Multi-stage containerized builds
• Kubernetes Helm Charts - Enterprise deployment support
• Go Install Support - Direct installation via go install
• GitHub Actions Integration - CI/CD pipeline integration
• Documentation Site - Comprehensive docs with interactive examples
• Performance Benchmarks - Automated performance regression testing

🎯 Community & Integration:

• Language Server Protocol - IDE integration support
• GitHub App - Repository analysis bot
• Slack/Teams Integration - Team collaboration features
• API Client Libraries - Go, Python, JavaScript clients
• Template Gallery - Pre-configured analysis templates
• Community Plugins - Marketplace for custom analyzers

🤝 Contributing

PRs + issues welcome. Please:

1. Run go fmt ./... & go vet ./...
2. Keep analyzer + server filtering logic in sync
3. For UI changes include screenshot or short GIF

📄 License

MIT (add a LICENSE file if distributing publicly).

Happy mapping! Open an issue for feature ideas or refinement suggestions.