graph json Format

graph.json Format

graph.json is the core data file produced by codebase-vis generate. It stores the full dependency graph in graphology JSON format. The interactive visualizer (graph.html) reads this file to render the graph.

Top-Level Structure

{
  "options": { ... },
  "attributes": {},
  "nodes": [ ... ],
  "edges": [ ... ]
}

Section	Purpose
options	Graph metadata (type, multi, self loops)
attributes	Reserved for semantic summaries (populated by explain)
nodes[]	Every file, external package, and class/function entity
edges[]	Dependency relationships (arrows) between nodes

options

Metadata about the graph:

{
  "type": "mixed",
  "multi": true,
  "allowSelfLoops": true
}

• multi: true — two nodes can have multiple edges between them
• allowSelfLoops: true — a file could theoretically import itself

nodes[]

File Node

{
  "key": "src/utils/cache.js",
  "attributes": {
    "dependencies": ["node:fs", "./helper.js"],
    "label": "cache.js",
    "community": "src/utils",
    "color": "#4E79A7",
    "language": "JavaScript",
    "x": 45.23,
    "y": 67.89,
    "size": 8
  }
}

Field	Meaning	Example
key	Unique ID (usually the file path)	"src/utils/cache.js"
label	Name shown on the node	"cache.js"
dependencies	What this file imports	["express", "./helper"]
community	Which module/group it belongs to	"src/utils"
color	The node's color (one per community)	"#4E79A7"
language	Programming language	"JavaScript"
x, y	Initial position (ForceAtlas2 rearranges)	45.23
size	Node radius (proportional to degree)	8

External Package Node

{
  "key": "express",
  "attributes": {
    "external": true,
    "npm": true,
    "label": "express",
    "community": "dependencies",
    "color": "#2d6a4f"
  }
}

external: true indicates this isn't a file in your project. npm: true means it was found in package.json.

Entity Node (class/function/method)

{
  "key": "src/utils/cache.js::loadCache",
  "attributes": {
    "label": "loadCache",
    "kind": "function",
    "community": "src/utils",
    "color": "#4E79A7",
    "size": 3
  }
}

The key combines the file path and the entity name with ::. kind can be "class", "function", or "method".

edges[]

Each edge represents a dependency between two nodes:

{
  "source": "src/cli/commands/query.js",
  "target": "src/cli/shared.js",
  "attributes": {
    "relationship": "imports"
  }
}

Field	Meaning
source	The node that has the dependency
target	The node that is depended upon
relationship	Type of relationship

Relationship Types

Type	Meaning	Visual
imports	File A imports/uses File B	Solid arrow
contains	A file contains a class/function	Dashed arrow

Contains Edge Example

{
  "source": "src/utils/cache.js",
  "target": "src/utils/cache.js::loadCache",
  "attributes": {
    "relationship": "contains"
  }
}

attributes — Semantic Summaries

Initially empty {}. After running codebase-vis explain, node attributes get a semantic_summary field describing what the file does. The full content varies based on the LLM response, but follows this pattern:

{
  "attributes": {
    "semantic_summary": "Handles caching of parsed file data using mtime and size fingerprints..."
  }
}

Summary

graph.json
├── options       → graph rules (type, multi, self-loops)
├── attributes    → AI summaries (empty until `explain`)
├── nodes[]       → every file + package + class/function
│   ├── key       → unique ID
│   └── attributes
│       ├── label       → display name
│       ├── dependencies → what it imports
│       ├── community   → module / "dependencies" / "entities"
│       ├── color       → hex color
│       ├── language    → detected language
│       ├── external    → true if package
│       └── kind        → "class" / "function" / "method"
└── edges[]       → arrows between nodes
    ├── source    → from node
    ├── target    → to node
    └── attributes
        └── relationship → "imports" (solid) or "contains" (dashed)