Knowledge Graph (AKA Site)

This repository contains the codebase for the backend Clojure application known as Site, 'The Knowledge Graph' or less formally 'KG'.

This codebase is forked from a JUXT project called Site (all JUXT projects are 4 letter words for some reason) but contains some Thirdbridge specific changes (such as authn setup) and should be thought of as a Thirdbridge codebase that happened to begin life as an opensource project.

The general idea behind Site is that APIs (queries/mutations/types etc) should be defined as a schema and not defined in code. Currently supported schema formats are Graphql and OpenAPI, but almost all Thirdbridge projects will use GraphQL so this document will focus on that.

This schema should follow the GraphQL specification (for compatibility with other tooling) and Site should be able to transform GraphQL queries and mutations into backend (SQL/Datalog) queries, either implicitly (for common CRUD use cases) or using an explicitly defined function (written in Clojure, or deployed in a lambda).

Detailed documentation on how to install and use Site can be found here, but the section below will be more tailored to Thirdbridge (assumes macOS).

Installation

Prerequisites

Before you start, you’ll need to have the following installed:

• Homebrew (you probably already have this, type brew to see if it’s installed)

  • /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• Java (using SDKMan for easy updates/version switches):

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java
sdk current # should be java 17, though any version of Java after 9 will work with Site

• Clojure

  • brew install clojure/tools/clojure

• Babashka

  • brew install borkdude/brew/babashka

• entr

  • brew install entr

• rlwrap

  • brew install rlwrap

Clone this repo

git clone https://github.com/third-bridge/site

Start the server

cd site
./bin/site-dev

The first time you run this Clojure will download some dependencies which could take a while depending on your internet speed. If everything goes as planned, you should soon see 'System started and ready' in the terminal.

Leave this process running, and check back if you get any 500 errors, this is where you will find logs related to Site (or XTDB).

Connecting to the REPL

A Clojure REPL is an interactive console into the running Clojure process, much like the console tab in a browsers developer tools.

To connect, we will use a socket connection with netcat, though you if you are familiar with Clojure tooling, you may wish to use an nREPL through your IDE/editor.

Run this in a terminal (a different terminal to the site server you ran above, make sure that is still running or the following command will not work)

rlwrap nc localhost 50505

You should now be 'logged in' to the Site repl, you can now run any Clojure code such as (inc 1).

Site also has several helper functions already available for use on first startup, you can see the code for these in src/juxt/site/alpha/repl.clj, but for this guide we will ignore the details and just run the one command that we need to set everything up.

(init!)

This command will 'install' an admin REST and GraphQL API, a console frontend, and some other things Site needs to function.

To check if it worked, visit this page.

You will see a very basic looking login form, this is a placeholder to mock out Thirdbridges authentication layer, enter "admin" for both the username and password to log in. You can add more users if you need to using the put-superuser! function available from the REPL.

You should see the two admin APIs, you can click the links to see a Swagger or GraphiqL playground containing documentation and interactive queries for those APIs.

Next Steps

And that’s it! you now have a fully functioning Knowledge Graph running locally. You can now run a next-gen frontend project like the Specialist Extranet