Voyager is a tool for engineers to quickly pull together architecture diagrams that describe how their systems fit together. There are a couple of things that distinguish Voyager from other tools:

  • Code-first - Diagrams are created using Taxi, our language for describing data. You describe your services and data models using a lightweight syntax and the diagram is automatically generated
  • Data as a first-class citizen - We think a key aspect of understanding how a collection of systems fit together is about the data that connects them. We can get a much more valuable understanding of the coupling between systems by highlighting the data models that are being shared.

Why we like it

We’re excited about being able to make Voyager publicly available. We think it’s useful for a range of use cases, whether it’s sketching out a design for a greenfield project, or documenting the details of your existing systems.

There have been many diagramming tools used by engineers over the years, why would we want a new one?

The tools we’ve reached for recently, for example Mermaid and PlantUML, are useful but are fairly general-purpose and don’t have a close alignment with our code. What we love about them though is that they’re lightweight, open source, have good plugins available for popular IDEs, and the output can be checked into source control.

What we’d like in addition is something that makes it easier to describe the detail of how a collection of systems connect to one another. Specifically, the APIs, message queues, or databases and the data models which are accessed.

Part of the solution is to lean on schema languages, such as OpenAPI which capture the concerns of an individual system. That’s useful when looking at a system in isolation, but more often we want to get a view of an ecosystem of microservices . That’s what we’re trying to capture here.

In order to do that, we’ve created a language called Taxi to describe services and data.

Taxi - a language for data

Taxi brings some key principles to describing data - it’s lightweight, open source, and check-in-able.

Describing your data is difficult enough and it shouldn’t be made any more complicated by the language. We’ve designed it to be hand writable, but also to have tools and plugins available to be able to generate it from other schema languages and code, providing that tight connection back to the underlying systems where possible.

In the Voyager samples you’ll notice that we used more than just primitive types for object properties. The Id of a Film isn’t just a number or string, it’s FilmId. That’s because we think that understanding the meaning of your data is extremely important. So important in fact that it should be captured in our code and schemas to help people understand our systems.

This is important in Voyager when we look at it from the lens of understanding our data as part of a wider ecosystem and not just in isolation for one system. The models and property names for the same piece of data might differ between systems, but using Taxi we can use a type system to express how they relate to each other.

Where it’s going

Voyager is one component of our wider platform, Vyne, that eliminates integration code between services. By leveraging the relationships between types, Vyne is able to automate the integration across your stack.

We think Voyager is a useful tool for engineers by itself so we’ve extracted it to a standalone app that we can release separately. We’re also working on open-sourcing the code for it, but we’ve got some work to do on modularising our code base before we can get to that.

This is also part of a broader project we’re working on to help teams with understanding the connections between their systems. For a team managing a collection of systems, there’s no good repository of knowledge for collecting and describing how those systems interact with each, and with the wider world whether that’s internal or external systems.

Having a simple method to produce a diagram is great, but we’re all about eliminating work not just moving it.

The next step will be to provide a simple way of connecting your schemas to Voyager to help generate the Taxi and diagrams for you and provide that link back to the source code, along with a raft of UX ideas.

We’re keen to hear what you think! Head over to our Slack channel or hit us up on Twitter (@martypitt, @michaelstoneldn)