Asterism: Turning Large Codebases into Interactive Visual Maps
Subtitle: How I built a VS Code extension that uses language-server capabilities and interactive graphs to help developers understand how code is connected.
Introduction
Understanding a large codebase is one of the hardest parts of software development.
When joining an unfamiliar project, developers often start by opening files and following imports, function calls, class definitions, and references manually. That works reasonably well for small projects, but becomes increasingly difficult as the codebase grows.
A function may call another function several layers deep. A class may inherit from another class defined in a different folder. A variable may be used across multiple methods. A change to one symbol may affect code that is not immediately obvious from the file being edited.
The problem isn't necessarily that the code is poorly written.
The problem is that the relationships inside the codebase are difficult to see.
That observation led to my idea for Asterism, a VS Code extension designed to turn those relationships into an interactive visual map.
Instead of only reading code line by line, developers can explore a graph of functions, methods, classes, interfaces, variables, files, and folders — and move between that visual representation and the actual source code.
The Problem with Understanding Large Codebases
Software is naturally represented as text.
Developers write:
function A() {
B();
}
function B() {
C();
}
A human can understand this small example immediately.
But imagine the same relationship spread across:
- 500 files
- thousands of functions
- dozens of classes
- multiple inheritance relationships
- shared variables
- deeply nested folders
- several layers of abstraction
Finding relationships manually becomes expensive.
Consider a seemingly simple question:
"If I change this function, what other parts of the application might be affected?"
You may need to:
- Find the function.
- Find its references.
- Identify callers.
- Inspect those callers.
- Follow additional calls.
- Check related classes.
- Check inherited implementations.
- Check variables or fields being used.
- Navigate between multiple files.
The information exists inside the codebase, but it is distributed across many source files and language constructs.
Asterism approaches the problem from a different direction:
What if the relationships already understood by the development environment could be turned into an interactive graph?
What Is Asterism?
Asterism is a Visual Studio Code extension for exploring the structure and relationships of a codebase through interactive graphs.
The name comes from the astronomical concept of an asterism — a recognizable pattern formed by stars.
That idea maps nicely to software.
A codebase contains many individual "points":
- Functions
- Methods
- Classes
- Interfaces
- Variables
- Files
- Folders
And relationships connect those points.
For example:
┌─────────────┐
│ Controller │
└──────┬──────┘
│ calls
▼
┌─────────────┐
│ Service │
└──────┬──────┘
│ calls
▼
┌─────────────┐
│ Repository │
└─────────────┘
Asterism turns relationships like these into an interactive graph that developers can explore.
How Asterism Works
At a high level, the process looks like this:
VS Code Workspace
│
▼
Workspace Scanner
│
▼
VS Code Language APIs
│
├── Symbols
├── Calls
├── References
├── Definitions
└── Type Relationships
│
▼
Relationship Model
│
▼
Graph Generation
│
▼
Cytoscape.js
│
▼
Interactive Webview
The important design decision here is that Asterism does not try to build a custom parser for every programming language.
Instead, it makes use of capabilities that VS Code and the installed language extensions already provide.
That makes the architecture considerably more language-neutral.
The Language-Server Advantage
One of the most important technical decisions in Asterism is relying on VS Code's language-service and language-server ecosystem.
Modern development environments already understand a lot about source code.
Depending on the language and installed extension, VS Code can provide information about things such as:
- Symbols
- Definitions
- References
- Call hierarchies
- Incoming calls
- Outgoing calls
- Type hierarchies
- Implementations
- Symbol relationships
Rather than rebuilding all of that knowledge from scratch, Asterism asks VS Code's language infrastructure for the information it needs.
Conceptually:
Source Code
│
▼
Language Extension
│
▼
Language Server / Service
│
▼
VS Code APIs
│
▼
Asterism
│
▼
Interactive Graph
This is particularly useful because programming languages have very different syntax and semantics.
A custom parser-based approach would require maintaining language-specific parsing and analysis logic.
With Asterism's approach, much of that language-specific work remains within the existing VS Code ecosystem.
A practical consequence
If VS Code has appropriate language support installed for a programming language, Asterism can potentially use the information exposed by that language support.
The quality and completeness of the resulting graph therefore depend partly on what the language service provides.
Main Features
Asterism is built around several kinds of code relationships.
Function and Method Calls
The graph can show relationships between functions and methods.
For example:
authenticate()
│
▼
validateUser()
│
▼
findUser()
This makes it possible to explore both directions:
- Outgoing calls: What does this function call?
- Incoming calls: What calls this function?
This is useful when investigating execution flow or estimating the potential impact of a change.
Class Inheritance
Object-oriented code often contains relationships that are difficult to understand when spread across multiple files.
Asterism can visualize inheritance relationships:
BaseController
▲
│ inherits
│
UserController
This provides another dimension of understanding beyond function calls.
Interface Implementations
Interfaces can also form important architectural relationships.
For example:
PaymentProvider
▲
│ implements
│
StripePaymentProvider
Visualizing these relationships can make larger object-oriented systems easier to navigate.
Variable and Field References
Not every important relationship is a function call.
A function may depend heavily on:
- A global variable
- A class field
- A shared object
- A configuration value
Asterism can represent relationships involving variables and class fields as well.
This helps answer questions such as:
"Which parts of the code use this value?"
From Workspace to Graph
The typical Asterism workflow is intentionally simple.
1. Open a project
Open an existing project or workspace in VS Code.
2. Open Asterism
Click the Asterism icon in the VS Code Activity Bar.
3. Workspace scanning
Asterism scans the workspace and builds its available file representation.
4. Browse the project
The Activity Bar sidebar provides a workspace-oriented view of folders and files.
5. Search
If the project is large, developers can search for a file rather than manually navigating through folders.
6. Generate a graph
Click a file to generate a graph related to that source.
You can also generate a graph representing the workspace.
7. Explore
Once the graph appears, you can:
- Click nodes
- Search symbols
- Filter relationships
- Trace connected nodes
- Collapse structures
- Double-click symbols
- Follow symbols under the cursor
8. Return to source code
Double-clicking a symbol allows you to jump back to its source code.
The goal is to make visual exploration and traditional code navigation work together rather than treating them as separate workflows.
The Activity Bar Workflow
One of the usability decisions behind Asterism was to make the extension feel like a natural part of VS Code.
Instead of requiring developers to remember commands or navigate complicated menus, Asterism has a dedicated entry point in the Activity Bar.
The workflow becomes:
Activity Bar
│
▼
Asterism Sidebar
│
├── Browse folders
├── Browse files
├── Search
└── Workspace graph
│
▼
Interactive graph
│
▼
Source code
This reduces the number of steps required to move from:
"I want to understand this part of the project"
to:
"Show me how this code is connected."
Keeping Large Graphs Understandable
A graph can become difficult to use if everything is displayed at once.
Imagine a graph containing hundreds or thousands of nodes.
Even if the underlying data is correct, displaying everything simultaneously can produce something visually overwhelming.
Asterism therefore provides several mechanisms for controlling graph complexity.
Grouping
Nodes can be grouped by:
- Folder
- File
- No group
For example:
src/
├── controllers/
│ ├── UserController
│ └── AuthController
│
├── services/
│ ├── UserService
│ └── AuthService
│
└── repositories/
└── UserRepository
Grouping provides a higher-level structure around the graph.
Collapsing
Folders, files, and classes can be collapsed.
Instead of showing every individual node:
UserService
├── createUser()
├── updateUser()
├── deleteUser()
├── validateUser()
└── notifyUser()
the graph can represent the larger structure more compactly.
This is important because visualization is not simply about displaying more information.
It is about displaying the right amount of information at the right time.
Filtering Relationships
Not every relationship is useful for every investigation.
Sometimes you only care about function calls.
At another point, you may want to understand inheritance.
Asterism provides filtering for relationship categories including:
- Calls
- Inheritance
- Variable references
This allows developers to reduce visual noise while investigating a particular question.
For example:
"Show me only the call flow."
rather than:
"Show me every relationship the system knows about."
Searching Inside the Graph
Large graphs introduce another navigation problem.
Even after generating a graph, finding one particular symbol can be difficult.
Asterism therefore supports symbol search inside the graph.
This allows a developer to move from:
"I know the symbol I need."
to:
"Show me where that symbol sits in the architecture."
That combination of search + visualization is particularly useful for large projects.
Tracing Connections
Asterism also allows developers to select a node and trace its relationships.
The idea is simple:
A
│
▼
┌─────B─────┐
│ │
▼ ▼
C D
Selecting B can make its surrounding relationships easier to identify.
This helps developers focus on a specific part of a larger graph without losing the broader context.
Following the Symbol Under the Cursor
Another useful workflow is following the symbol currently under the cursor.
Instead of manually generating a new graph every time you move to another symbol, Asterism can use the active symbol to update the graph.
This creates a more continuous workflow between code editing and visual exploration.
Jumping Between Graph and Source Code
Visualization is useful, but developers ultimately work with source code.
Asterism therefore treats the graph as a navigation layer rather than a replacement for the editor.
Double-clicking a symbol can take the developer back to its source.
The workflow becomes:
Source
↓
Graph
↓
Explore relationship
↓
Select symbol
↓
Open source
↓
Continue investigation
This creates a feedback loop between visual understanding and actual implementation.
Why Visual Code Maps Are Useful
The usefulness of a graph depends on the question being asked.
There are several situations where visual relationships can be particularly helpful.
1. Learning an unfamiliar project
When joining a new project, developers need to build a mental model.
A visual map can help answer:
- Where are the important components?
- Which functions connect?
- Which classes depend on others?
- Where does execution flow?
2. Planning refactoring
Before changing a function or class, it is useful to understand its relationships.
A graph can provide another perspective on potential dependencies.
Instead of immediately modifying code, developers can first investigate how the symbol connects to the surrounding system.
3. Understanding legacy systems
Legacy applications often contain years of accumulated behavior.
Documentation may be incomplete or outdated.
The code itself becomes the most reliable source of information.
A visual representation can help developers gradually reconstruct the system's structure.
4. Finding highly connected functions
Some functions become central points in an application.
They may have:
- Many callers
- Many outgoing calls
- Numerous references
These highly connected areas can be useful places to investigate when trying to understand architecture or potential change impact.
5. Reviewing dependencies
A graph can provide a visual representation of relationships that are otherwise spread across files.
This can make dependency investigation more approachable.
6. Investigating bugs
When debugging, developers frequently ask:
"How did execution get here?"
Following incoming and outgoing relationships can help reconstruct the path surrounding a problematic symbol.
7. Developer onboarding
New developers often need to understand a system before they can contribute effectively.
A visual exploration tool can complement:
- Documentation
- Code reviews
- Architecture diagrams
- Existing development guides
8. Understanding inheritance
Inheritance structures can become particularly difficult when classes are distributed across packages and directories.
A graph makes those relationships easier to inspect.
9. Estimating change impact
Before modifying an important symbol, developers can inspect its connections and identify areas that may deserve additional attention.
It isn't a replacement for careful testing, but it can provide useful context before making a change.
Technical Architecture
Asterism is built around several core technologies.
TypeScript
The extension is implemented using TypeScript.
TypeScript provides:
- Static typing
- Better tooling
- Improved maintainability
- Strong integration with the VS Code extension ecosystem
For an extension that coordinates workspace scanning, language-service requests, graph generation, and UI communication, maintaining clear contracts between components is particularly useful.
VS Code Extension API
The VS Code Extension API provides the foundation for Asterism.
It gives the extension access to the development environment it is running inside.
Asterism uses VS Code capabilities for things such as:
- Workspace interaction
- File-system events
- Commands
- Activity Bar integration
- Sidebar views
- Language-service/provider functionality
- Editor interaction
- Theme information
This lets Asterism behave as part of VS Code rather than as an entirely separate application.
Language-Service Provider Commands
The language layer is one of the most important parts of the architecture.
Rather than parsing every language independently, Asterism uses VS Code's available language-service capabilities to discover relationships.
Conceptually, the extension asks questions such as:
What symbol is this?
↓
Where is it defined?
↓
What references it?
↓
What does it call?
↓
What calls it?
↓
What types are related to it?
The exact information available can vary depending on the language extension and language server.
That variability is an important part of the architecture.
Cytoscape.js
Once relationships have been discovered, Asterism needs a way to render them.
For this, it uses Cytoscape.js.
Cytoscape.js is designed for interactive graph and network visualization.
Asterism represents code relationships using graph concepts:
Node = code entity
Edge = relationship
For example:
UserController ──calls──> UserService
or:
AdminController ──inherits──> BaseController
This creates a natural mapping between software architecture and graph structures.
fCoSE Layout
They also need to be positioned in a way that makes relationships understandable.
Asterism uses the fCoSE graph layout to organize graph structures.
The purpose of the layout is to produce a more readable arrangement of interconnected nodes, particularly when grouping structures are involved.
This matters because graph visualization is partly a data problem and partly a spatial problem.
The same relationships can be much easier or harder to understand depending on how they are arranged visually.
Webviews
Asterism's interactive graph interface runs through a VS Code Webview.
This provides a bridge between the VS Code extension environment and web-based UI technologies.
Conceptually:
VS Code Extension
│
│ messages / data
▼
Webview
│
▼
Cytoscape.js Graph
This allows the graph interface to provide interactive behaviors such as:
- Selecting nodes
- Searching
- Filtering
- Collapsing
- Tracing
- Navigating
while remaining inside VS Code.
Activity Bar and Sidebar
The Activity Bar provides the primary entry point for the extension.
The sidebar handles workspace exploration and file selection.
This separation is useful because it keeps two different concerns distinct:
Sidebar
"What part of the project do I want to investigate?"
Graph
"How is that part of the project connected?"
VSIX Packaging
Asterism is packaged as a VSIX, the standard packaging format for VS Code extensions.
This allows users to install the extension directly into VS Code.
The same packaging approach also makes it possible to distribute the extension through the VS Code ecosystem.
Language Support Through VS Code
Asterism's language strategy is worth emphasizing.
It isn't designed around the assumption that one parser can understand every programming language.
Instead:
Asterism
│
▼
VS Code Language APIs
│
▼
Installed Language Extension
│
▼
Language Server
This provides an abstraction layer.
For example, Asterism doesn't necessarily need to know every syntactic rule of a language in order to ask:
"What calls this function?"
The language service may already know that.
Asterism's responsibility becomes:
- Request relationship information.
- Interpret the returned information.
- Convert it into a common internal graph representation.
- Render that representation.
- Let the developer interact with it.
This is one of the architectural choices that makes the project interesting to me.
Design and Usability Decisions
Technical functionality is only part of building a developer tool.
The other challenge is making the functionality easy to use.
Simple Entry Point
The Activity Bar provides an obvious place to start.
Developers don't need to learn a complicated command sequence before seeing the extension.
Automatic Workspace Scanning
Workspace scanning happens automatically.
This removes an additional setup step and allows the sidebar to immediately represent the project.
Fast Path from File to Graph
The sidebar is designed around a simple interaction:
Find file → Click file → Explore graph
That keeps graph generation close to the user's existing project navigation workflow.
Grouping and Collapsing
Large graphs can quickly become unreadable.
Grouping and collapsing allow developers to move between different levels of abstraction.
You can think of this as:
Workspace
↓
Folder
↓
File
↓
Class
↓
Method
The user can decide how much detail is appropriate for the current investigation.
Theme Integration
A developer tool should feel native to its host environment.
Asterism supports:
- Light themes
- Dark themes
- High-contrast VS Code themes
This allows the graph interface to adapt to the developer's VS Code environment.
Workspace File Updates
Projects change constantly.
Files can be:
- Created
- Edited
- Renamed
- Deleted
Asterism responds to these workspace changes and refreshes the file representation accordingly.
This avoids treating the workspace as a static snapshot.
Performance Considerations
Visualizing code relationships introduces practical limitations.
Theoretically, a graph can contain a huge number of nodes and edges.
Practically, that doesn't mean displaying everything at once is a good user experience.
Asterism therefore applies limits intended to keep the interface usable.
For example, it can limit the number of files and graph nodes involved in analysis.
It also skips common generated or dependency-heavy directories such as:
node_modules/
dist/
build/
.venv/
venv/
These directories can contain large amounts of code that generally isn't useful when initially exploring the application's own source.
Language Server Startup
Another practical consideration is that language servers may need time to initialize.
If a language service is still loading or hasn't finished analyzing a workspace, the information returned to an extension may be incomplete.
Therefore, the graph should not always be interpreted as an absolute representation of every relationship in the workspace at every instant.
The quality of the results depends on the language support available in VS Code.
Large Workspaces
Very large workspaces may require adjusting configuration such as:
- Maximum files
- Call depth
- Graph limits
The objective isn't to claim that every codebase can be visualized without constraints.
The objective is to provide useful exploration while recognizing that code analysis and graph rendering both have practical boundaries.
Development Process and AI-Assisted Coding
Asterism began from my original idea and core concept.
I defined the overall direction of the project, including:
- The product concept
- Technical direction
- Feature requirements
- Architecture decisions
- User experience decisions
- Testing decisions
- Branding
- Integration requirements
- Packaging and release preparation
During implementation, I used GPT-5.6 LUNA Agentic Coding as a development assistant.
The AI-assisted workflow helped with areas such as:
- Exploring implementation approaches
- Generating and refining code
- Debugging
- Iterating on features
- Reasoning through technical problems
- Improving implementation details
However, this was an AI-assisted development process, not an AI-owned project.
The project direction, decisions, evaluation, testing, integration, and final development responsibility remained under my direction.
I think this distinction is important.
AI coding assistants can significantly change how software is developed, but using an AI tool doesn't mean the tool independently owns the product or replaces the developer's responsibility for architectural and engineering decisions.
For Asterism, I treated AI as a development partner and coding assistant while remaining responsible for the project itself.
Lessons Learned
Building Asterism highlighted several lessons that extend beyond this particular project.
1. Use Existing Language Infrastructure
One of the strongest lessons was the value of building on top of capabilities that already exist.
Creating a parser and semantic analyzer for every supported language would dramatically increase the complexity of the project.
Using VS Code's language ecosystem allows Asterism to focus more heavily on visualization and developer experience.
2. Language-Neutral Architecture Matters
Different languages have different concepts and semantics.
A language-neutral graph model provides an abstraction:
Language-specific information
↓
Common model
↓
Graph nodes
+
Graph edges
That separation makes it easier to think about relationships independently of syntax.
3. Mapping Language Results to Graph Nodes Is Difficult
Getting information from a language service is only half the problem.
That information needs to become stable graph entities.
For example, the system needs to reason about:
Symbol
↓
Definition
↓
File
↓
Position
↓
Graph Node
Different language servers can return information with different levels of completeness.
Connecting these results reliably is an important engineering challenge.
4. Incomplete Results Are Normal
Language services aren't guaranteed to return perfect information at every moment.
Workspaces may still be loading.
Some symbols may not resolve.
Some relationships may not be available.
A robust visualization system needs to handle these cases gracefully rather than assuming that every query returns a complete dataset.
5. Large Graphs Need Constraints
More data doesn't automatically mean more useful information.
A graph with thousands of nodes might contain valuable information but still be practically impossible to understand.
Grouping, filtering, collapsing, and sensible limits are therefore essential features rather than optional UI improvements.
6. A Simple Sidebar Workflow Matters
Developer tools compete with an existing workflow.
If a developer needs to execute several commands just to inspect one file, the tool becomes harder to adopt.
The Activity Bar → Sidebar → File → Graph workflow keeps the interaction simple.
7. Powerful Analysis vs. Readable Interface
There is always a balance.
More relationships can produce a more complete analysis.
But displaying more relationships can also produce more visual noise.
Asterism's development reinforced an important principle:
A useful developer tool isn't necessarily the one that displays the most information. It's the one that makes the important information easier to understand.
Future Improvements
Asterism's current architecture leaves room for several future improvements.
Some possibilities include:
Graph Export
Export graph views as:
- PNG
- SVG
This would make it easier to include visual architecture diagrams in documentation or technical discussions.
Saved Graph Views
Allow developers to save graph configurations for a workspace and return to them later.
Analysis Caching
Caching previously discovered relationships could reduce repeated analysis work in suitable situations.
External Library Visualization
External library calls could potentially appear as visually differentiated or faded nodes, helping distinguish application code from dependencies.
Advanced Dependency Analysis
Future versions could provide richer dependency relationships beyond the current graph categories.
Graph History
A history mechanism could allow developers to move backward and forward between explored graph states.
Refactoring Impact Analysis
A future impact-analysis feature could help developers investigate potential affected areas before modifying a symbol.
Project-Level Summaries
Higher-level summaries could provide a more architectural view of the project before diving into individual symbols.
More Language-Service Features
As VS Code's language capabilities evolve, Asterism can potentially make use of additional language-service functionality.
More Language Edge Cases
Automated testing around language-specific and language-server edge cases would help improve reliability across different projects and language environments.
Installation and First Use
Asterism can be installed using the VSIX package or, when available, through the VS Code Marketplace.
The general workflow is:
1. Install Asterism
Install the VSIX through VS Code, or install Asterism from the Marketplace when it is available there.
2. Open a Workspace
Open the project you want to investigate in VS Code.
3. Open Asterism
Click the Asterism icon in the Activity Bar.
4. Let the Workspace Scan
Asterism scans the workspace and builds the file representation.
5. Choose What to Explore
Select an individual file or generate a graph for the workspace.
6. Explore
Use:
- Search
- Filtering
- Node selection
- Tracing
- Grouping
- Collapsing
to investigate the relationships.
7. Return to Code
Double-click a symbol to jump back to its source code.
The basic loop is:
Open project
↓
Open Asterism
↓
Scan workspace
↓
Select file / workspace
↓
Generate graph
↓
Explore relationships
↓
Jump back to source
Conclusion
Large codebases aren't difficult only because they contain a lot of code.
They're difficult because the relationships between that code are distributed across thousands of individual elements.
A developer might understand every function in isolation and still struggle to understand how the entire system fits together.
That's the problem Asterism is trying to address.
By combining VS Code's language-service capabilities, TypeScript, Cytoscape.js, fCoSE, Webviews, and the VS Code Extension API, Asterism turns code relationships into an interactive visual environment.
The key idea isn't to replace source code with diagrams.
It's to provide another way of looking at the same system.
Instead of only asking:
"What does this file contain?"
developers can also ask:
"What is this connected to?"
"What calls this?"
"What does this call?"
"Which classes are related?"
"Where is this symbol used?"
"What does the surrounding architecture look like?"
That shift — from reading code exclusively as text to also exploring it as a network of relationships is the core idea behind Asterism.
And as codebases continue to grow, I think tools that help developers see software structure rather than only read it will become increasingly valuable.
Top comments (0)