Spring Boot Architecture Mapper

Turn your Spring Boot codebase into a living, interactive architecture diagram — directly inside VS Code.

Spring Boot Architecture Mapper performs zero-configuration static AST analysis of your Java source files and renders a real-time, interactive graph of every Spring component, their dependency relationships, inheritance chains, and interface implementations. No build required. No runtime. No external service.

Features at a Glance

Getting Started

Requirements

• VS Code 1.85 or later
• A Java workspace containing Spring Boot source files (.java)
• Git (optional — required for Code Churn heatmap)

Install

Search for Spring Boot Architecture Mapper in the VS Code Extensions Marketplace and click Install.

Or install manually:

code --install-extension panguluri.spring-mapper

Generate a Diagram

1. Open a folder or workspace containing Spring Boot Java sources.

2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run:

   Spring Mapper: Generate Graph
   

3. The diagram panel opens beside the active editor. Spring components appear as nodes; arrows show injected dependencies.

Blast Radius from the Explorer

Right-click any .java file in the Explorer and select Spring Mapper: View Blast Radius to instantly highlight every component that would be affected by a change to that file.

The Graph

Node Types

Each node is colour-coded by Spring stereotype:

Edges

Layouts

Switch between three layout algorithms from the toolbar:

• Force (default) — physics-based D3 force simulation; nodes organise naturally by coupling
• Dagre — clean left-to-right hierarchical layout
• Column — grouped by stereotype type

Code Churn Heatmap

Click 🔥 Churn in the toolbar to overlay git commit history onto the graph.

The extension runs git log locally and counts how many commits touched each .java file. Commit counts are normalised to a 0–1 scale (95th-percentile capping, so a single mega-file does not wash out the rest) and mapped to a three-stop colour gradient:

Stable ──── 💙 #4cc9f0 ──── 💛 #ffd60a ──── ❤️ #f72585 ──── Volatile

Each node also shows a 🔥N pill displaying the raw commit count.

The 🔥 Churn button is disabled until git history has been loaded. It activates automatically in the background after the initial scan completes.

Use cases:

• Identify high-risk refactoring targets before a sprint
• Surface architectural hot-spots that may benefit from decomposition
• Prioritise code review attention on the most volatile classes

MCP Server — AI Graph Query Interface

When the extension activates, it automatically starts a local Model Context Protocol (MCP) server on http://127.0.0.1:3579. This gives AI coding assistants (GitHub Copilot, Cursor, Claude Desktop, etc.) structured, queryable access to your architecture graph.

The status bar shows $(radio-tower) MCP :3579 when the server is running. Hover over it for the exact config snippet.

Connect GitHub Copilot

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "spring-arch-mapper": {
      "type": "sse",
      "url": "http://127.0.0.1:3579/sse"
    }
  }
}

Connect Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "spring-arch-mapper": {
      "type": "sse",
      "url": "http://127.0.0.1:3579/sse"
    }
  }
}

Available Tools

Example Copilot Prompts

Once connected, you can ask Copilot naturally:

"Refactor PaymentService to be async — what's the blast radius?"

Copilot will invoke get_blast_radius({ symbol: "PaymentService" }) behind the scenes and write a refactor that accounts for every downstream dependency.

"Which classes are most likely to have bugs right now?"

Copilot calls get_high_churn_nodes({ limit: 10 }) and reasons over git history.

"How does a request flow from OrderController to the database?"

Copilot calls get_call_chain({ from: "OrderController", to: "OrderRepository" }) and traces the exact path.

Toolbar Reference

How It Works

The extension performs static AST analysis entirely within VS Code — no compilation, no runtime, no network calls.

.java source files
      │
      ▼
  JavaFileParser          regex-based AST extraction
  (per file)              — stereotypes, annotations, field injections,
                            implements/extends chains, @Gateway detection
      │
      ▼
  WorkspaceScanner        builds SpringGraph
  (workspace-wide)        — deduplication, transitive implements resolution,
                            superclass chain traversal
      │
      ├──► GraphPanel (React + @xyflow/react)
      │         force layout, community detection, heatmap, filters
      │
      └──► GraphMcpServer (HTTP/SSE)
                MCP tools queryable by AI assistants

What is detected

• Spring stereotypes — @RestController, @Controller, @Service, @Repository, @Component, @Configuration
• Dependencies — @Autowired fields, constructor injection, @Resource
• Interfaces — implements relationships including FQN (com.example.Foo) and generic bounds (Comparable<T>)
• Inheritance — extends chains (including through non-Spring abstract base classes)
• Spring Integration Gateways — interfaces annotated with @Gateway or @MessagingGateway

What is NOT detected

• Runtime-only beans (beans created via @Bean factory methods are not traced)
• Reflection-based injection
• XML-configured Spring beans

Extension Settings

No configuration required. The extension works out of the box.

The MCP server port (3579) is currently fixed. If port 3579 is in use, the status bar will show $(error) MCP failed — stop the process occupying that port and reload the VS Code window.

Known Limitations

• Very large workspaces (5 000+ Java files) may take several seconds to scan. Progress is shown in the VS Code status bar.
• The parser uses regex-based analysis, not a full Java compiler. Edge cases in complex generics or annotation processors may not be resolved.
• Code Churn requires the workspace to be inside a git repository with commit history.

Contributing

Pull requests are welcome. The extension is written in TypeScript (extension host + React webview).

# Clone and install
git clone <repo-url>
cd spring-boot-arch-mapper
npm install

# Build (extension host + webview bundle)
npm run build

# Type-check only (fast)
npx tsc --noEmit
npx tsc --noEmit -p tsconfig.webview.json

# Watch mode (extension host)
npm run watch

# Watch mode (webview)
npm run watch:webview

Press F5 in VS Code to launch the Extension Development Host.

License

MIT — see LICENSE for details.