Pivograph

Draw how an organization fits together.

Pivograph turns one JSON file into an interactive map of an organization's projects, platforms and partners, and of how each one uses the others. Write it by hand, have an AI agent write it from this documentation, or import a published .well-known descriptor.

Pivograph showing Rulezet in the middle, linked to MISP, Vulnerability-Lookup, CTI-Transmute, Velociraptor, AIL, Flowintel, MISP-Workbench, zsazsa and Pivotick
Projects linked to Rulezet, from examples/rulezet.json Explore it live

Where to start

Open the app

It opens on the Rulezet example. Drop your own JSON file on the page, or press New to start from ready-made types, then add nodes and edges with the forms.

Open the app

Import a well-known

If the organization publishes /.well-known/open-contributions.json, Graph → Import an organization… turns it into a map in one step: projects, data, standards and relationships.

How the import works

Ask an AI agent

Point any AI agent at the guide and name the organization. It follows the mapping procedure and returns one JSON file you open in the app.

Prompt template   llms-full.txt

One file for the whole map

Nodes are the things being mapped: projects, platforms, datasets, partners. Edges say how two of them are related, and which way the arrow goes. Types give a family of nodes or edges the same look, and tags become small pills you can filter by.

Any field left out is inherited from the node's type, then from a built-in default, so a map can start with a single node and grow.

Every field, with defaults   JSON schema   minimal.json

json
{
  "meta": { "title": "Projects linked to Rulezet" },
  "nodeTypes": {
    "project": {
      "color": "#3b63f3",
      "shape": "hexagon",
      "image": "icons/project.svg",
      "imageFit": "icon"
    }
  },
  "nodes": [
    {
      "id": "rulezet",
      "label": "Rulezet",
      "type": "project",
      "github": "rulezet/rulezet-core"
    },
    {
      "id": "misp",
      "label": "MISP",
      "tags": ["threat-intelligence"]
    }
  ],
  "edges": [
    {
      "from": "rulezet",
      "to": "misp",
      "label": "pushes rules as MISP events"
    }
  ]
}

The guide

Overview
What a map contains, and where to find the app, the source and the files for AI agents.
Quick start
Use it in the browser, or run it locally.
Mapping an organization
The procedure to map an organization: sources, nodes, edges, types, validation, a checklist and a prompt.
Document format
Every field of meta, nodes, edges, types and tags, with defaults and validation rules.
Examples
A complete checked map and a minimal one.
Open Contributions Descriptor
How a .well-known/open-contributions.json file becomes a map.
Embedding
Show a map on another site: iframe parameters and the postMessage protocol.
Hugo
Add a graph to a Hugo site: Hugo builds the JSON from its pages, draws it as SVG without JavaScript, and shows the interactive graph with it.
Reports
Export a map as JSON, Pivotick data, a picture, or a PDF or Markdown report, and how the text is written.
Using the app
Editing nodes and edges, GitHub details, filters and saving.
Architecture
How the code is organized, and the Pivotick details it works around.
Development
Scripts, tests, deployment and this documentation.
For AI agents
The files an AI agent should read and produce.