Code review
Diagrams in your repo
Keep read-only copies of your diagrams next to the code, with Mermaid previews that GitHub, GitLab, Bitbucket and Azure DevOps draw in pull requests. Works with any git host.
The files
.nodeslate/
config.json links the codebase to its diagrams (written by connect_codebase; yours to edit)
checkout-flow.json the exact diagram, with where it came from (generated)
checkout-flow.md the same diagram as Mermaid, drawn by git hosts (generated)Repositories linked before November 2026 have .nodeslate.json at the root instead. Tools still read it; move it to .nodeslate/config.json when convenient.
Linking several diagrams
One config.json holds every diagram the code is drawn in. To link another one, add its line under diagrams in the same file; never make a second file. Asking your AI tool to “connect this diagram too” does this for you: it passes the file as it is to connect_codebase and gets it back with the new diagram added.
{
"nodeslate": 1,
"workspace": "Acme",
"folder": "Platform",
"diagrams": {
"Checkout flow": "https://nodeslate.io/d/8f3k…",
"Orders schema": "https://nodeslate.io/d/92b2…",
"Services": "https://nodeslate.io/d/2e9d…"
}
}A pull then writes a .json and an .md file for each of them.
Each diagram's .json file starts with a header naming the diagram, its link and the revision it holds:
{
"document": { … },
"nodeslate": {
"id": "8f3k…",
"note": "Generated by Nodeslate. Don't edit this file: …",
"revision": 45,
"title": "Checkout flow",
"updated_at": "2026-11-20T09:12:44+00:00",
"url": "https://nodeslate.io/d/8f3k…"
}
}Three ways to pull
1. Ask your AI tool
Say “pull the latest diagrams”. The tool calls pull_diagrams with .nodeslate/config.json and the revisions it already has, writes the files that changed, and tells you what changed. Commit them with your code.
2. Download from the app
Open the diagram, choose Export → For your repo, and put both files in .nodeslate/ at the repository's root.
3. From a script or CI
GET /diagrams/:id/file returns one file as plain text; GET /diagrams/:id/mirror returns both, with their paths.
curl -fsS -H "Authorization: Bearer $NODESLATE_KEY" \
"https://nodeslate.io/api/public/v1/diagrams/DIAGRAM_ID/file?format=json" > .nodeslate/checkout-flow.jsonThis script pulls every diagram in .nodeslate/config.json, naming the files after their titles there (needs curl and jq):
#!/usr/bin/env bash
set -euo pipefail
API="${NODESLATE_API:-https://nodeslate.io/api/public/v1}"
CONFIG=.nodeslate/config.json; [ -f "$CONFIG" ] || CONFIG=.nodeslate.json
jq -r '.diagrams | to_entries[] | "\(.key)\t\(.value)"' "$CONFIG" |
while IFS=#x27;\t' read -r title link; do
curl -fsS -G "$API/diagrams/${link##*/}/mirror" --data-urlencode "name=$title" \
-H "Authorization: Bearer $NODESLATE_KEY" |
jq -c '.files | to_entries[]' | while read -r file; do
path=$(jq -r .key <<<"$file"); mkdir -p "$(dirname "$path")"
jq -j .value <<<"$file" > "$path"
done
doneKeep it fresh in CI
Run the script on a schedule and commit what changed. Store the key as a secret named NODESLATE_KEY.
# .github/workflows/diagrams.yml
on:
schedule: [{ cron: "0 3 * * *" }]
workflow_dispatch:
permissions: { contents: write }
jobs:
pull:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: bash scripts/pull-diagrams.sh
env: { NODESLATE_KEY: ${{ secrets.NODESLATE_KEY }} }
- run: |
git config user.name "nodeslate-bot"
git config user.email "nodeslate-bot@users.noreply.github.com"
git add .nodeslate && git commit -m "Pull diagrams from Nodeslate" && git push || echo "No changes"Use a key made for the workspace the diagrams live in, with no more reach than CI needs.
Stuck, or missing something? Contact us.