Newton Graph Library

This repository contains learning and prototype code for a high-level dashboard for architects and stakeholders. The goal is to visualize architectures in large organizations as organisms that live and breathe with deployments, problems, etc. These real-time visualizations could instead reveal insights about how Conway's Law applies to the organization.

This newtonjs-graph library is just the frontend. For details, see the explanation at the bottom.

Readme Contents

• Live Demo →
  • Graph Frontend →
  • Data Editor (interactive BFF mock) →
• Install
  • For Browsers
  • For Webpack
• API Documentation →
  • Network
  • Graph
  • Customize Styles
• Architecture - where is the backend?

Example Graphs

The following show two different renders from the same demo data set:

D3.js Engine	Webcola Engine
d3-force creates a "harmonious" distribution of nodes	cola.js can create directional graphs

Highlight Relationships with Colors

In both examples above, the "Documents Service" is the highlighted node. The colors indicate a relationship to this node:

For more information view API Documentation →

Install

For Browsers

Grab the newton.bundle.min.js and newton.css files from the dist/ folder. Then include them in your HTML file.

<!-- import library as `Newton` global -->
<script src="./newton.bundle.min.js" type="text/javascript"></script>
<script type="text/javascript">
	const network = new Newton.Network(…)
	const graph = new Newton.Graph(…)
</script>

Note: the documentation refers to module syntax. If you are using the pre-built distribution, you will need to remember to use the Newton.Graph instead of Graph, etc.

Then continue directions below to define your Network and Graph.

For Webpack

First, install the library

npm install --save @newtonjs/graph

Then in your javascript, include them as you would any other library:

const Graph = require('@newtonjs/graph').Graph
const Network = require('@newtonjs/graph').Network

And for CSS, you can include the pre-built styles in an SCSS file like so:

@import "~@newtonjs/graph/dist/newton.css";

Network - Data Wrapper

A Network is essentially a data wrapper. Its biggest advantage is that it dynamically calculating links between nodes, based on a unique identifier uid, instead of array indexes.

Here is an example data set from the demo:

const data = {
	nodes: [
		{ id: 'w', label: 'Web Frontend' },
		{ id: 'm', label: 'Mobile Device' },
		{ id: 'b', label: 'Monolith Backend' },
		{ id: 'd', label: 'Database' },
	],
	links: [
		{ source: 'w', target: 'b' },
		{ source: 'm', target: 'b' },
		{ source: 'b', target: 'd' }
	]
}

Graph - Visualization

While Network handles the data, Graph handles the visualizations, including layout, animations, etc.

const network = new Network(data.nodes, data.links)
const graph = new Graph({
	width: window.innerWidth,
	height: window.innerHeight,
	flow: 'horizontal',	
	draggable: true,
	network: network // required
})

graph.init()
graph.on('node:click', (n) => {
	graph.highlightDependencies(n, { arrows: true })
})

Customize Styles

Starting in version 0.2.0, you can use CSS variables to customize your graph. You should not need to edit the pre-built newton.css file.

For example, in your CSS, you can just include the following variables and change them as needed:

:root {
	--graph-bg-color: --var(--navy-darker);
	--label-font-family: 'Roboto', sans-serif;
	--label-font-size: 14px;
	--label-text-shadow: 1px 1px 5px rgba(0,0,0,0.2);
	--link-stroke-width: 1px;
	--node-stroke-width: 3px;
}

For a list of all available variables, please see newton/graph/css/variables.scss

Development

Clone this repository

git clone https://github.com/julie-ng/newtonjs-graph

Install dependencies

First install the dependencies required:

npm install

Preview

To view the prototype in the browser, run

npm run demo:dev

which starts the webpack dev server and automatically opens http://localhost:9000 in a browser window.

Architecture - where is the backend?

So how will this work? This project is very much a work in progress, but the current concept is illustrated below. This repository newton-graph is "Newton UI" in the diagram.