diff --git a/README.md b/README.md index 7108adf..bdd599f 100644 --- a/README.md +++ b/README.md @@ -21,60 +21,68 @@ them can be overwhelming. - Provides reproducible navigation via: - Clicking on vertices within the current view - Type ahead search for vertex properties -- HTML5 SVG display for easier export and scaling -- [Generalized JSON format](./docs/data_format.md) that is not application specific +- HTML5 SVG display scaling +- Cayley Graph database for incremental traversal of large graphs +- GraphQL API for vertex queries -## Graph Data +## Requirements -Currently, only the following project creates valid RDF graphs for this project: +You will need to install the following locally: -- [django_codecrumb](https://github.com/bijanvakili/django-codecrumb) +- [Docker](https://www.docker.com/) v19+ +- [node.js](https://nodejs.org/) v6+ +- [yarn](https://yarnpkg.com/en/) v0.24+ -All graph data is stored in Cayley DB. This project runs Cayley in a Docker container. +## Graph Database -## Configuration +### Graph Data -Edit `etc/render_settings.json` to specify how to displays your graph data +Currently, only the following project creates valid RDF graphs for this project: -```json -{ - "startVertexId": "", - "vertexColumnPageSize": 8, - "images": [ - ... - ] -} -``` +- [django_codecrumb](https://github.com/bijanvakili/django-codecrumb) + +All graph data is stored in Cayley DB. This project runs Cayley in a Docker container. -## Load Data +### Load Data -NOTE: Database must be _shut down_. +NOTE: Database must be initially _shut down_. Copy your Cayley DB import file into the `./data` folder (e.g. `filename.nq.gz`) and run the following Docker command: -```bash -docker-compose run --rm --entrypoint "cayley load -i /import/filename.nq.gz" db -``` + docker-compose run --rm --entrypoint "cayley load -i /import/filename.nq.gz" db -## Volume Inspection +### Volume Inspection To or manipulate the Cayley DB files, run the following: -```bash -docker-compose run --rm shell -``` + docker-compose run --rm shell -## Running locally +### Running -You'll only need to install the following: +You can start the Cayley graph database using Docker as follows: -- [node.js](https://nodejs.org/) v6+ -- [yarn](https://yarnpkg.com/en/) v0.24+ + docker-compose up -d db + +## Web Application + +### Configuration + +Edit `etc/render_settings.json` to specify how to displays your graph data + +```json +{ + "startVertexId": "", + "vertexColumnPageSize": 8, + "images": [ + ... + ] +} +``` ### Building -Run the following to install all the necessary build dependencies using `yarn` and runtime dependencies using [`webpack`](https://webpack.github.io/). +Run the following to install all the necessary build dependencies using `yarn`: yarn install @@ -86,12 +94,14 @@ Run the following to build and bundle all Javascript code into the `./dist` subd Then run the following to run the web server: - yarn run web + GRAPHWALKER_RENDER_SETTINGS=etc/render_settings.json yarn run web Finally, open the following URL in your web browser: open http://localhost:9080/ +## Local Development + ### Running a Test server [tmux](https://github.com/tmux/tmux/wiki) is required to run a test server using watch mode on all source files: @@ -100,15 +110,19 @@ Finally, open the following URL in your web browser: This will run multiple watch windows for both client and server. -### Local Development +### git hooks Set up the git pre-commit hook as follows: -```sh - ln -s ../../scripts/pre-commit .git/hooks/pre-commit -``` + ln -s ../../scripts/pre-commit .git/hooks/pre-commit + +### GraphQL testing + +Open up the following to use the Apollo GraphQL playground, an interactive and in-browser GraphQL IDE + + open http://localhost:9080/graphql -#### Cleanup +## Cleanup To remove build files, run the following: diff --git a/Vagrantfile b/Vagrantfile deleted file mode 100644 index 8a1f059..0000000 --- a/Vagrantfile +++ /dev/null @@ -1,65 +0,0 @@ -# -*- mode: ruby -*- -# vi: set ft=ruby : - -# All Vagrant configuration is done below. The "2" in Vagrant.configure -# configures the configuration version (we support older styles for -# backwards compatibility). Please don't change it unless you know what -# you're doing. -Vagrant.configure(2) do |config| - # The most common configuration options are documented and commented below. - # For a complete reference, please see the online documentation at - # https://docs.vagrantup.com. - - # Ubuntu Desktop 14.04 LTS (Trusty Tahr) - config.vm.box = "box-cutter/ubuntu1404-desktop" - - # Disable automatic box update checking. If you disable this, then - # boxes will only be checked for updates when the user runs - # `vagrant box outdated`. This is not recommended. - # config.vm.box_check_update = false - - # Create a forwarded port mapping which allows access to a specific port - # within the machine from a port on the host machine. In the example below, - # accessing "localhost:8080" will access port 80 on the guest machine. - # config.vm.network "forwarded_port", guest: 80, host: 8080 - - # Create a private network, which allows host-only access to the machine - # using a specific IP. - # config.vm.network "private_network", ip: "192.168.33.10" - - # Create a public network, which generally matched to bridged network. - # Bridged networks make the machine appear as another physical device on - # your network. - # config.vm.network "public_network" - - # Share an additional folder to the guest VM. The first argument is - # the path on the host to the actual folder. The second argument is - # the path on the guest to mount the folder. And the optional third - # argument is a set of non-required options. - # config.vm.synced_folder "../data", "/vagrant_data" - - # Provider-specific configuration so you can fine-tune various - # backing providers for Vagrant. These expose provider-specific options. - # Example for VirtualBox: - # - config.vm.provider "virtualbox" do |vb| - # Display the VirtualBox GUI when booting the machine - vb.gui = true - - # Customize the amount of memory on the VM: - vb.memory = "1024" - end - # - # View the documentation for the provider you are using for more - # information on available options. - - # Define a Vagrant Push strategy for pushing to Atlas. Other push strategies - # such as FTP and Heroku are also available. See the documentation at - # https://docs.vagrantup.com/v2/push/atlas.html for more information. - # config.push.define "atlas" do |push| - # push.app = "YOUR_ATLAS_USERNAME/YOUR_APPLICATION_NAME" - # end - config.vm.provision "shell" do |shell| - shell.path = "script/vagrant/setup-tools.sh" - end -end diff --git a/docs/data_format.md b/docs/data_format.md deleted file mode 100644 index 0633458..0000000 --- a/docs/data_format.md +++ /dev/null @@ -1,89 +0,0 @@ -# Graphwalker JSON format - -## Introduction - -The data format is meant to be non-application specific as `graphwalker` to be a general graph visualization tool. - -## General structure - -The JSON currently only provides two root level properties which represent arrays of vertices and edges. - -```json -{ - "vertices": [ - ... - ], - "edges": [ - ... - ] -} -``` - -### Vertex format - -```json -{ - "id": "fb7a0fe33d793ac7f0c86391fe4fd450677af4c3", - "label": "Fancy Pants Vertex", - - "searchableComponents": ["Fancy", "Pants"], - - "properties": { - ... - } -} -``` - -|Property|Type |Required|Description| -|:-------|:-------|:------:|:----------| -|`id`|_string_|Y|Unique identifier for vertex. [SHA1](https://en.wikipedia.org/wiki/SHA-1) hashes are recommended| -|`label`|_string_|Y|Human readable display name| -|`searchableComponents`|_array_|N|Strings to match against the vertex for type-ahead search| -|`properties`|_object_|N|Free form user-defined properties (anything that is valid JSON)| - -### Edge Format - -```json -[ - { - "id": "1d942b8a57669a54d067591f07ac0d1c917413c1", - "label": "inheritance", - - "source": "c51ae819a2f6c83be2585b75ac650959b78866d9", - "dest": "d629496c37d7f808029091d5d2d02e07d72c134e", - - "properties": {...} - }, - ... -] -``` - -|Property|Type |Required|Description| -|:-------|:-------|:------:|:----------| -|`id`|_string_|Y|Unique identifier for edge| -|`label`|_string_|Y|Human readable display name| -|`source`|_string_|Y|`id` of the source (originating) vertex for this edge| -|`dest`|_string_|Y|`id` of the destination (terminating) vertex for this edge| -|`properties`|_object_|N|Free form user-defined properties (anything that is valid JSON)| - -## Future items - -* TODO Refactor JSON into a _serialization_ format for large graph data sources -* TODO URLs for representation images - -Graph - vertices - edges - -Vertex - id - label (displayName) - searchableComponents - properties {} - -Edge - id - source - dest - label - properties {} diff --git a/docs/references.md b/docs/references.md index 1e8ff3f..d06b0c9 100644 --- a/docs/references.md +++ b/docs/references.md @@ -1,34 +1,52 @@ -# Quick References +# Technology Stack References -## Language and Platform +## Languages -* [Typescript](https://www.typescriptlang.org/docs) -* [Javascript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) -* [node.js](https://nodejs.org/) -* [less](http://lesscss.org/) +- [Typescript](https://www.typescriptlang.org/docs) +- [Javascript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) +- [less](http://lesscss.org/) +- [GraphQL](https://graphql.org/graphql-js/graphql/) -## UI Libraries +## Database -* [React](https://facebook.github.io/react/docs/react-api.html) -* [Bootstrap](https://getbootstrap.com/) -* [d3.js](https://d3js.org/) -* [Redux](https://redux.js.org/) -* [react-redux](https://github.com/reactjs/react-redux) -* [redux-thunk](https://github.com/gaearon/redux-thunk) -* [reselect](https://github.com/reduxjs/reselect) -* [typesafe-actions](https://github.com/piotrwitek/typesafe-actions) +- [Cayley](https://cayley.gitbook.io/cayley/) -## Utility Libraries +## Backend -* [lodash v4](https://lodash.com/) -* [classnames](https://jedwatson.github.io/classnames/) +- [node.js](https://nodejs.org/) +- [Apollo Server](https://www.apollographql.com/docs/apollo-server/) +- [express](https://expressjs.com/) + +## Frontend + +- [React](https://facebook.github.io/react/docs/react-api.html) +- [Bootstrap](https://getbootstrap.com/) +- [d3.js](https://d3js.org/) +- [Redux](https://redux.js.org/) +- [react-redux](https://github.com/reactjs/react-redux) +- [redux-thunk](https://github.com/gaearon/redux-thunk) +- [reselect](https://github.com/reduxjs/reselect) +- [typesafe-actions](https://github.com/piotrwitek/typesafe-actions) +- [Apollo React Client](https://www.apollographql.com/docs/react/) (a.k.a. Apollo Boost) + +## Utility + +- [lodash v4](https://lodash.com/) +- [classnames](https://jedwatson.github.io/classnames/) ## Development Tools -* [tslint](https://palantir.github.io/tslint/) -* [yarn](https://yarnpkg.com/en/docs/cli/) -* [webpack](https://webpack.js.org/configuration/) +- [markdownlint](https://github.com/DavidAnson/markdownlint) +- [tslint](https://palantir.github.io/tslint/) +- [prettier](https://prettier.io/) +- [yarn](https://yarnpkg.com/en/docs/cli/) +- [webpack](https://webpack.js.org/configuration/) +- [grunt](https://gruntjs.com/) +- [graphql-codegen](https://graphql-code-generator.com/) +- [tmux](https://github.com/tmux/tmux/wiki) +- [nodemon](https://nodemon.io/) +- [busybox](https://busybox.net/) ## Theory -* [Graph Terminology](http://btechsmartclass.com/DS/U3_T8.html) +- [Graph Terminology](http://btechsmartclass.com/DS/U3_T8.html)