Visualizing the Graph (GraphView)
Relevant source files
The following files were used as context for generating this wiki page:
The GraphView module provides a force-directed visual representation of the Archivum knowledge base. It renders wiki pages and extracted entities as nodes, with edges representing semantic and structural relationships discovered by the Wiki Agent. This feature allows users to navigate their knowledge base non-linearly, identifying clusters of related information and potential gaps in their documentation.
The system is designed to be highly responsive, with a target initial render time of under 2 seconds for up to 500 nodes. It serves as a primary interface for browsing the persistent wiki, complementing standard search and wikilink navigation.
Sources: archivum-prd-v1.0.md:223-231, README.md:12-25
Architecture and Data Flow
The graph visualization pipeline begins with raw source ingestion and concludes with a rendered interactive view in the React frontend. Relationships are extracted from markdown content and stored in a graph database, which is then queried by the frontend or MCP clients.
Backend Data Handling
Relationships are stored in Neo4j (or the Kuzu embedded fallback) as directed edges. The backend exposes endpoints and tools to retrieve these relationships, specifically GET /api/graph and the graph_neighbors MCP tool.
Frontend Rendering
The frontend consumes a JSON structure consisting of a list of nodes and edges. While the product requirements suggest vis.js or Sigma.js for rendering, the visualization implementation in graph_export.py utilizes a self-contained SVG-based circle layout for offline exports.
The diagram shows the end-to-end flow from data ingestion to the final graph visualization.
Sources: archivum-prd-v1.0.md:223-235, apps/backend/archivum/scripts/graph_export.py:151-165, apps/backend/archivum/mcp/server.py:146-153
Data Models and Schema
The graph structure distinguishes between primary page nodes and specific entity nodes extracted from the text.
Node and Edge Definitions
| Component | Types/Labels | Description |
|---|---|---|
| Node Types | page, person, concept, organisation, tech, place | Differentiates between actual wiki pages and abstract/named entities. |
| Edge Relationships | references, related-to, contradicts, mentions | Defines the semantic nature of the link between two nodes. |
Sources: archivum-prd-v1.0.md:226-227, apps/backend/archivum/ingest/agent.py:46-51, apps/backend/archivum/mcp/demo.py:27-52
JSON Structure for Visualization
The graph is exchanged using a standard JSON format compatible with common visualization libraries:
{
"nodes": [
{"id": "index", "label": "Index", "type": "page"},
{"id": "Archivum", "label": "Archivum", "type": "entity", "entity_type": "wiki"}
],
"edges": [
{"from": "index", "to": "mcp-setup", "type": "references", "label": "references"}
]
}
Sources: apps/backend/archivum/scripts/graph_export.py:15-30, apps/backend/archivum/mcp/demo.py:84-100
Implementation Details
Graph Export Utility
The project includes a graph_export.py script that generates self-contained visualization artifacts. This is used for generating demo reports and can fall back to mock data if the database is unavailable.
render_html: Generates a self-contained HTML page using SVG for rendering nodes and edges without requiring CDN assets._normalize_edges: Ensures that every edge has alabelfield, mapping the internaltypefield to the label for frontend compatibility.export_demo: Generates mock exports for testing purposes.
Sources: apps/backend/archivum/scripts/graph_export.py:86-180, README.md:220-240
Interaction and UI Logic
In the React frontend, the GraphView supports several interaction patterns:
- Click to Open: Clicking a node navigates the user to the corresponding wiki page.
- Node Highlighting: Searching or selecting nodes highlights the node and its immediate neighbors.
- Zoom and Pan: Standard navigational controls for large graphs.
Sources: archivum-prd-v1.0.md:228-230, apps/frontend/src/api.test.ts:312-325
MCP Integration
The knowledge graph is exposed to AI agents via the graph_neighbors tool. This allows an LLM to "walk" the graph to find related context that might not be captured by semantic search alone.
This sequence illustrates how an AI assistant programmatically explores the graph relationships.
Sources: apps/backend/archivum/mcp/server.py:146-153, README.md:210-215
Performance and Constraints
The GraphView is architected for home server environments, where RAM may be limited.
- Neo4j Memory Footprint: Neo4j is the preferred graph engine but is considered "heavy" (recommending 2GB RAM).
- Kuzu Fallback: If hardware constraints are met, the system falls back to Kuzu, an embedded graph database with a much smaller footprint.
- Update Latency: The graph is updated within 5 seconds of an ingest completion to ensure the visualization remains current.
Sources: archivum-prd-v1.0.md:204-206, 230, 275-276, README.md:175-185
Conclusion
Visualizing the Graph (GraphView) is a critical component for making knowledge "compound" in Archivum. By providing both a human-readable force-directed graph and an agent-accessible neighbors API, the system ensures that the relationships extracted by the AI are useful for both manual navigation and automated query synthesis. The implementation prioritizes resilience through its standalone export capabilities and database fallbacks.