Introduction

What is Arc?

Arc is Terrastruct's feature to bridge the gap between the visual documentation of a system and the data that powers it. Arc achieves this by bringing five things:

  1. A set of integrations to pull data seamlessly from popular services, e.g. Github, AWS, etc.
  2. A set of endpoints that you can push data to in popular schemas, formats, and protocols (e.g. Telegraf schema with JSON over HTTP).
  3. A simple DSL (domain specific language) for querying the above data. In presentation mode, these queries are run every few seconds whenever there's new relevant data.
  4. A way to easily reference query results in your diagrams.
  5. An API on each diagram component that lets you program its properties based on query results.

Together, it provides an easy way to get system data into Terrastruct, ask questions about that data, and program your diagram based on that data.

What's it for?

Currently, diagrams made for the purpose of documenting a system can only describe the system as snapshots. Valuable but ephemeral information is not included, and instead often supplemented when presenting the diagram (e.g. show a picture of the diagram and talk through it). This leads to great diagrams either losing the original context, or solidify the context in the form of a video, making it hard to change when the actual system changes. All this leads to diagrams being deprecated quickly, but usually the latest one will continue to get referenced, even if months or even years old. And when people look at outdated diagrams, all sorts of questions run through their head:

Static diagramStatic diagram

Static diagram

When these questions are answered on the diagram, three things happen:

  1. The diagram becomes the view of your system, instead of a snapshot of it when it was created.
  2. The diagram avoids drifting from reality, as any discrepancies will be made clear visually (e.g. the last time a commit was made to this repo was 2 years ago, it's getting no traffic, etc).
  3. New perspectives on the data are unlocked by presenting them in the layout of your choosing, versus on an arbitrary grid-placement. You can architect it in a way that reveals cause and effect, and with Terrastruct's unique layering mechanisms, add context on multiple levels of abstraction (e.g. click into a server with a CPU spike, and see the individual processes allocation).
Diagram with live dataDiagram with live data

Diagram with live data

Arc is not meant to replace your analytics dashboards. Our goal is to let you create the most humanly-perceivable view of what are highly abstract, intangible systems. These software systems power the world, but the mental models of how they work are highly divergent even among the teams building them. This leads to ineffective collaboration and coordination, which is the root cause of many bugs, security issues, inconsistent product experiences, etc — in general, bad software. Terrastruct wants to change that, and help you create the visual documentation that lets your team ship at its best.