nodeslate

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

Repository root
.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/config.json
{
  "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.json

This script pulls every diagram in .nodeslate/config.json, naming the files after their titles there (needs curl and jq):

scripts/pull-diagrams.sh
#!/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 done

Keep 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.