# How the code-review-graph Export Functionality Works: GraphML, Neo4j, and Obsidian Explained

> Explore the code-review-graph export functionality. Learn how to serialize your codebase into GraphML, Neo4j, and Obsidian formats from the provided Python library.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-07-22

---

**The code-review-graph library serializes analyzed codebases from a `GraphStore` into multiple interchange formats—including GraphML, Neo4j Cypher, and Obsidian Vault—via specialized functions in [`code_review_graph/exports.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/exports.py) that consume a normalized data payload from `export_graph_data`.**

The `code-review-graph` repository provides a complete pipeline for transforming static code analysis into portable graph formats. Whether you need to visualize relationships in Gephi, import structures into a graph database, or browse code complexity in Obsidian, the export functionality handles normalization, serialization, and atomic file operations through a consistent Python API.

## The Core Export Pipeline

Every export format follows an identical two-step pattern. First, the shared `export_graph_data` function (defined in [`code_review_graph/visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py)) extracts nodes, edges, and community data from the `GraphStore` into a normalized dictionary. Second, format-specific writers in [`code_review_graph/exports.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/exports.py) serialize this payload to disk.

```python
from code_review_graph.visualization import export_graph_data

# Normalize the store into a portable payload

data = export_graph_data(store)  # Contains nodes, edges, communities

```

All export functions accept a `GraphStore` instance and a destination `Path`, automatically creating parent directories via `Path.mkdir(parents=True, exist_ok=True)`.

## JSON Export with Atomic Writes

The `export_json` function (lines 23-51 of [`exports.py`](https://github.com/tirth8205/code-review-graph/blob/main/exports.py)) provides the simplest serialization path. It writes UTF-8 JSON using an atomic file replacement strategy to prevent corruption during interrupted writes.

```python
from pathlib import Path
from code_review_graph.exports import export_json

export_json(store, Path("output/graph.json"))

```

Under the hood, the function writes to a temporary file first, then calls `os.replace` to atomically move the completed file into place. This ensures that readers never encounter a partially written JSON object.

## GraphML Export for Visualization Tools

**GraphML** export targets desktop visualization tools like Gephi, yEd, and Cytoscape. Implemented in `export_graphml` (lines 58-117 of [`exports.py`](https://github.com/tirth8205/code-review-graph/blob/main/exports.py)), this function generates XML conforming to the GraphML schema specification.

Each node receives `<data>` entries encoding **kind**, **file**, **language**, and **community** attributes. Edges include an `edge_kind` property distinguishing relationship types. This rich metadata preserves the analytical context when importing into external tools.

```python
from code_review_graph.exports import export_graphml

export_graphml(store, Path("output/graph.graphml"))

```

## Neo4j Cypher Export

For graph database ingestion, `export_neo4j_cypher` (lines 124-170 of [`exports.py`](https://github.com/tirth8205/code-review-graph/blob/main/exports.py)) generates executable Cypher statements. The output contains `CREATE` clauses for nodes and `MATCH...CREATE` patterns for relationships.

The implementation uses two helper functions to ensure syntactic correctness:
- **`_cypher_props`**: Converts Python dictionaries into Cypher property maps
- **`_cypher_escape`**: Sanitizes strings to prevent injection or parsing errors

```python
from code_review_graph.exports import export_neo4j_cypher

export_neo4j_cypher(store, Path("output/import.cypher"))

```

The resulting `.cypher` file can be pasted directly into the Neo4j Browser or executed via the `cypher-shell` command-line tool.

## Obsidian Vault Export

The **Obsidian** export generates a complete knowledge base as a directory of Markdown files. Unlike single-file formats, `export_obsidian_vault` (lines 192-444 of [`exports.py`](https://github.com/tirth8205/code-review-graph/blob/main/exports.py)) creates a hierarchical structure:

- One Markdown page per graph node with YAML front-matter metadata
- Wikilink syntax (`[[...]]`) connecting related entities
- Community overview pages aggregating members
- A global index page for vault navigation

The helper `_obsidian_slug` normalizes node names into file-safe identifiers.

```python
from code_review_graph.exports import export_obsidian_vault

export_obsidian_vault(store, Path("output/obsidian_vault"))

```

Opening the `obsidian_vault` folder in Obsidian reveals a browsable network where code entities, files, and communities function as interlinked notes.

## SVG Visualization Export

For static visualization, `export_svg` constructs a `networkx.DiGraph` from the normalized payload, applies color mapping by node **kind**, and renders using Matplotlib's Agg backend. This export requires the optional `matplotlib` dependency; the function raises a clear `ImportError` if the library is missing.

```python
from code_review_graph.exports import export_svg

export_svg(store, Path("output/graph.svg"))

```

The SVG output provides a quick overview suitable for documentation or presentation decks without requiring external tool installation.

## Command-Line Interface Integration

The CLI module at [`code_review_graph/cli.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/cli.py) (lines 1658-1685) exposes these exporters via the `--export` flag. The interface maps user input to the appropriate function:

```python
from code_review_graph.exports import (
    export_json,
    export_graphml,
    export_neo4j_cypher,
    export_obsidian_vault,
    export_svg,
)

# CLI dispatch example

export_mapping = {
    "json": export_json,
    "graphml": export_graphml,
    "neo4j": export_neo4j_cypher,
    "obsidian": export_obsidian_vault,
    "svg": export_svg,
}

```

This allows terminal users to invoke exports without writing Python scripts:

```bash
code-review-graph analyze ./src --export graphml --output ./graph.graphml

```

## Summary

- **All formats** consume the same normalized payload from `export_graph_data` in [`visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/visualization.py).
- **JSON** uses atomic file replacement via `os.replace` to prevent corruption.
- **GraphML** embeds rich metadata including community assignments and language tags.
- **Neo4j** output generates ready-to-run Cypher with sanitized string escaping.
- **Obsidian** creates a multi-file vault with YAML front-matter and wikilinks.
- **SVG** requires `matplotlib` and renders colored node networks.

## Frequently Asked Questions

### How does the code-review-graph export functionality normalize data before writing?

All exporters call `export_graph_data(store)` from [`code_review_graph/visualization.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/visualization.py) first. This function transforms the internal `GraphStore` representation into a standardized dictionary containing a nodes list, edges list, and community mappings, ensuring every format receives identically structured input regardless of the source analysis state.

### What prevents partial file writes during JSON export?

The `export_json` function writes to a temporary file in the same directory, then calls `os.replace` to atomically rename the temporary file to the final destination. This ensures that readers either see the complete previous file or the complete new file, never a partially written intermediate state.

### How does the Obsidian Vault export differ from GraphML?

While GraphML produces a single XML file optimized for graph visualization software, the Obsidian export generates an entire directory structure containing multiple Markdown files—one per node—complete with YAML front-matter metadata and wikilink syntax. This creates a navigable knowledge base rather than a graph interchange format.

### Which export formats require optional dependencies?

Only the **SVG** export requires an external dependency. The `export_svg` function attempts to import `matplotlib` lazily at runtime, raising an `ImportError` with a clear message if the library is not installed. JSON, GraphML, Neo4j, and Obsidian exports rely solely on the Python standard library.