We’ve all been there. You start documenting a system with a simple "Box and Arrow" diagram. At first, it’s clean. Then reality sets in.
You need to show which components are in the public subnet versus the private one. You need to distinguish between synchronous REST calls and asynchronous events. You need to highlight which services are within the scope of a specific compliance audit.
Before you know it, your PlantUML or Mermaid file is a 500-line wall of text. The biggest heartbreak? Nothing ages faster than a PDF of a system architecture.
The Problem: The "Diagramming Tax"
I’ve spent a lot of time in the trenches of software architecture documentation. Tools like PlantUML are fantastic for simple graphs, but they have a breaking point.
The "niggles" start when you want to annotate a graph without affecting the layout, or when you need to represent a node that lives in multiple logical worlds. PlantUML doesn't really allow you to attach metadata to a component without the tool trying to "draw" that metadata.
More importantly, these diagrams are write-only. You can't ask a PlantUML file: "Show me the blast radius if this internal service is compromised." You just have to squint at the spaghetti and hope your brain can parse the connections.
Enter GSL: Architecture as a Queryable Model
GSL (Graph Selector Language) is an experiment in treating architecture as data first, and an image second. It’s born from a simple desire: I wanted a format that was easy to version-control, easy to diff, and—most importantly—easy to explore.
GSL splits the problem into two distinct parts:
-
The Language: A way to describe the graph and annotate nodes with "Sets" using a simple
@tagsyntax. - The Query Language: An orthogonal tool to filter that graph and extract specific subgraphs.
1. Modeling Reality with Sets
In GSL, nodes aren't trapped in a rigid hierarchy. A component can belong to as many "Sets" as you need.
node web @public
node gateway
node userService @internal @auth
node database @internal @datastore
user -> web # Implicit node creation for speed
web -> gateway
gateway -> userService
userService -> database
The @internal tag isn't just a label; it’s a dimension. You aren't restricted by how the graph looks; you're describing what it is.
2. Exploring the Noise
The real "Aha!" moment didn't come from writing the parser; it came from looking at a massive, generated architectural graph and realizing I couldn't find what I was looking for.
By using an orthogonal query language, you can strip away the noise. If you only want to see the "Internal" world and how it connects to the outside, you run:
subgraph node in internal traverse both all
The result isn't just a list—the output is another GSL graph. This composability is the core of the experiment. You can pipe, filter, and zoom in on specific architectural stories without ever touching a mouse.
Beyond Documentation: The "Gut Feel" for Refactoring
While GSL is currently in its early stages (v0.4.x), the vision goes beyond just making better Mermaid charts.
I have a strong gut feel that by representing architecture in a queryable format, we open the door to automated architectural insights. Imagine being able to programmatically detect "architectural smells"—unintended transitive dependencies or security policy violations—before a single line of infrastructure is even deployed.
It moves us away from "drawing pictures" and toward advanced refactoring for systems, supported by tooling that actually understands the relationships we've defined.
An Ongoing Experiment
GSL is a labor of love implemented in Go. I chose Go not because it’s a requirement for the language, but because it allowed me to quickly build a robust first implementation. I've used tools like Participle for parsing while challenging the implementation through rigorous testing to ensure it matches the mental model I had in mind.
It’s still an experiment, and the query language is evolving rapidly. But the goal remains the same: Your architecture diagrams should be as searchable as your code.
Explore the project: If you're tired of static diagrams and want to see a different way of modeling systems, check out the repo at github.com/dnnrly/gsl-lang.
Top comments (0)