Onboarding for new team members

You're a new member to the team and you need a quick look around. Welcome!

What's the stack?

Let's start with a simple list of the platforms, tools, and techniques used in this product:

Architectural element	Technology	Why?
Cloud Provider	Azure (current) AWS (future)	UTA standard for technology services. We may be converting (or have already converted) some or all of our infrastructure to AWS; please see the engineering leadership team for further information.
Database	Aura DB v2025.06+[1], a managed version of Neo4j	A longer story, but driven by the nature of the domain, and by experience maintaining complex relationship graphs in relational databases over time. See the introduction.
API Language	Node.js & Typescript	Most popular, heavy experience at UTA, robust community, language innovation
API Framework	Express
Database driver	Neo4j's Javascript Driver	Supported, official
API Architectural Style	GraphQL
API Deployment Platform	The API is deployed as a federated graph on UTA's managed Kubernetes infrastructure. In Azure, this is called Azure Kubernetes Service. The API sits behind Azure API Management, and in turn each "subgraph" is federated using the Wundergraph Cosmo product.
API Design Tooling
Authentication	Microsoft Entra ID (formerly Azure Active Directory), Azure Entra External ID	UTA standard for authentication
Authorization
Source code control	GitHub	We do nearly everything possible in GitHub. This is where developers work.
Documentation	Vitepress	Docs as code, just a React app, currently deploys as private GitHub pages site (see the docs)
CI/CD	GitHub Actions	UTA engineering standard
Developer workstations

Learning about graph databases

Developers familiar with relational databases will find the Neo4j Cypher query language, and associated concepts, straightforward.

We recommend you start with free, self-paced training at Neo4j's Graph Academy. Take all the courses on the "beginner" track (even if you have considerable experience) to learn Neo4j, graph data modeling, and the basics of Cypher, the query language.

Understanding our data model

After you have a basic understanding of graph databases, review our data model that is documented here.

Environments

As of this writing we have a development environment for the authoritative data APIs and the back end database. We will soon be setting up production.

Accessing the API

TBD

Maintaining the API

TBD

Exploring and querying the database

Neo4j Browser

TBD (resolve issues with VPNs, Cyolo incompatibility)

Working with this documentation site

This documentation site is unique in that much of it was written before any implementation began. It is also unique because the doc is used by initialization scripts created by the data engineering team to provision Neo4j constraints and indexes.

The doc site you are reading is a statically generated web application. Writing documentation consists of writing or editing markdown documents and maintaining a table of contents file.

Vitepress

This static site generator is Vitepress, which is Vite & Vue-based.

WHY DID YOU PICK VITEPRESS?

We originally started with Docusaurus which had the advantage of letting us write docs using MDX, which enabled us to combine Markdown and React. We ultimately picked Vitepress because it's fast, and it looks great, although it does come with the minor drawback that because Vitepress is Vue-based, any custom components we write have to be Vue components. This has not been a problem.

WHY AREN'T YOU USING CONFLUENCE?

While Confluence is a UTA standard, it works against our design goal of having Authoritative Data feel like a standalone product that appeals to software developers. Good products have web sites with docs and references. In addition, the documentation here is maintained using standard software engineering practice: write in simple, text-based markdown files, commit to the repo, merge to main, deploy automatically. We have found we can get product managers unfamiliar with markdown or Git workflows up and running with short learning curve.

The site is indexed locally (in order to power the search feature) using Vitepress's indexing feature.

GitHub Pages

The doc site is deployed as a private GitHub pages site and is only accessible to UTA personnel that have access to the underlying repository, adm-site. The site has a custom domain configured; note there is also a UTA CNAME associated (https://mdm.unitedtalent.com) which is configured with a CNAME file in the root of the repo.

The site is automatically deployed on every push to the main branch by a GitHub workflow.

GitHub Pages documentation

Mermaid and vitepress-plugin-mermaid

Diagrams are written as code and rendered at site generation time by Mermaid. Mermaid is a popular, markdown-friendly way to write diagrams with a variety of diagram types available out of the box. Mermaid diagrams are natively supported in GitHub issues and wikis, and they are supported in Vitepress through the use of a plugin called vitepress-plugin-mermaid.

We recommend installing the mermaid extension for vscode in order to see mermaid previews while editing documentation.

How to set up your workflow for documentation updates

Local development

You will of course need a workstation with:

1. Git installed and configured
2. At least write access to the adm-site repo
3. Node and Npm installed (latest versions)

You will also need working knowledge of:

1. GitHub (including an account with write access to the repo and that is a member of the UTA github organization)
2. Cloning
3. Branching
4. Commits
5. Pushes
6. Pull requests
7. Merging

Here are the steps to set up locally:

1. Clone https://github.com/united-talent-agency/adm-site locally.
2. npm install all dependencies
3. Create a branch (preferably against a Jira ticket) to make the changes.
4. In a separate terminal window, run npm run docs:dev to start the development server; site will normally be hosted at localhost at port 5173.
5. Make edits to the markdown. As you save the file you'll notice the doc site updates.
6. Before you commit and push the branch, run npm run docs:build to ensure you have no dead links or other issues.
7. Commit and push the branch.
8. Open a pull request against main and wait for the codeowners to review your PR.

Codespaces

We've set up a fairly workable way to work on the doc in a virtual environment called a GitHub Codespace. If you just need a development workstation pre-configured to edit the docs, this may be a good option without forcing you to install all the required tools, clone the repo, and so on on your local machine.

That said, all of the prerequisites about git knowledge mentioned above still apply.

1. Make sure a UTA GitHub administrator has granted you permissions to create codespaces in the adm-site repository
2. Navigate to the adm-site repository in the browser.
3. Select the Code tab.
4. Create a branch as described before.
5. Select the green Code dropdown.
6. In the dialog, select the Codespaces tab.
7. Create a new codespace.

The codespace will be created with the docs checked out and the right tools installed. In addition, the npm run docs:dev command will be invoked and the port with the doc site will be forwarded.

It may take a minute to set up the codespace. To see the running site you have to select Ports in the terminal window, click on the side, and hit the Open in Web Browser or Preview buttons.

Rules for submitting doc change PRs

Now that the documentation is being used to create database constraints, there are a few rules:

1. All model changes must go through strict code review. This will be enforced.
2. Don't change the sections in the node or relationship detail pages; the scripts may be using the data in the markdown tables. Best not to rearrange headings, etc on the detail pages -- work within the current information architecture.
3. Consult with the VP of Product, Data Operations (@carmtk) if you are unsure about whether you should make a change.

---

1. Neo4j moved from semantic versioning to calendar versioning after the release known as v5. ↩︎