# raidslab/novagraph architecture

> Architecture diagram of the GitHub repository raidslab/novagraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raidslab/novagraph
- Repository: https://github.com/raidslab/novagraph

## Overview

NovaGraph is a local-first browser application for importing or building graphs, analyzing them, and interpreting results on an interactive canvas. Its principal workflow runs from the visualizer through MainController to graph storage and igraph analytics, then maps algorithm results back to the canvas and result table. The README documents local persistence, optional Cypher, and export as additional capabilities. Source excerpts confirm key controller, worker, and parsing responsibilities; unsampled subsystems are represented only where documented.

Main entry points: [`src/features/visualizer/index.tsx`](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/index.tsx) (Visualizer UI), [`src/MainController.ts`](https://github.com/raidslab/novagraph/blob/master/src/MainController.ts) (Main controller), [`src/app/routes.ts`](https://github.com/raidslab/novagraph/blob/master/src/app/routes.ts) (App routes), [`src/features/visualizer/algorithms/implementations/path-reachability/bellman-ford-a-all.tsx`](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/algorithms/implementations/path-reachability/bellman-ford-a-all.tsx) (Algorithm results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_routes["App routes<br/>[routes.ts]"]
  node_landing["Landing page<br/>[index.tsx]"]
  node_visualizer["Visualizer UI<br/>[index.tsx]"]
  node_renderer["Graph canvas<br/>[index.tsx]"]
end

subgraph group_orchestration["Orchestration"]
  node_main["Main controller<br/>[MainController.ts]"]
  node_algorithm_ui["Algorithm selection<br/>[algorithm-list.tsx]"]
  node_algorithm_results["Algorithm results"]
  node_layer_slice["Result encodings<br/>[index.ts]"]
end

subgraph group_graph_data["Graph data"]
  node_import["Graph import"]
  node_kuzu_controller["Kuzu controller<br/>[KuzuController.ts]"]
  node_kuzu_service["Kuzu services<br/>[KuzuBaseService.ts]"]
  node_query_helpers["Query helpers"]
  node_local_store[("Local graph store")]
end

subgraph group_analytics["Analytics"]
  node_igraph_controller["igraph controller"]
  node_worker["Analytics worker"]
  node_wasm["igraph WASM<br/>[graph.js]"]
end

subgraph group_exploration["Exploration tools"]
  node_cypher["Cypher query editor<br/>[index.tsx]"]
  node_query_output["Query results<br/>[query-output.tsx]"]
  node_compare["Result comparison<br/>[index.ts]"]
  node_export["Graph export"]
end

node_user(("Analyst"))

node_user -->|"opens app"| node_routes
node_routes -->|"routes to"| node_landing
node_routes -->|"routes to"| node_visualizer
node_user -->|"explores graph"| node_visualizer
node_visualizer -->|"uses orchestration"| node_main
node_visualizer -->|"displays graph"| node_renderer
node_visualizer -.->|"imports graph"| node_import
node_import -.->|"loads graph"| node_kuzu_controller
node_main -->|"controls storage"| node_kuzu_controller
node_kuzu_controller -->|"selects service"| node_kuzu_service
node_kuzu_service -->|"executes queries"| node_query_helpers
node_kuzu_service -.->|"persists locally"| node_local_store
node_visualizer -.->|"selects algorithms"| node_algorithm_ui
node_algorithm_ui -.->|"requests analysis"| node_main
node_main -->|"runs analytics"| node_igraph_controller
node_igraph_controller -->|"dispatches task"| node_worker
node_worker -->|"calls algorithms"| node_wasm
node_worker -.->|"returns results"| node_algorithm_results
node_algorithm_results -->|"maps result"| node_layer_slice
node_layer_slice -.->|"encodes canvas"| node_renderer
node_algorithm_results -.->|"shows output"| node_visualizer
node_visualizer -.->|"opens optional query"| node_cypher
node_cypher -.->|"submits query"| node_main
node_main -.->|"returns query data"| node_query_output
node_visualizer -.->|"compares results"| node_compare
node_visualizer -.->|"exports graph"| node_export

click node_routes "https://github.com/raidslab/novagraph/blob/master/src/app/routes.ts"
click node_landing "https://github.com/raidslab/novagraph/blob/master/src/features/landing/index.tsx"
click node_visualizer "https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/index.tsx"
click node_renderer "https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/renderer/index.tsx"
click node_main "https://github.com/raidslab/novagraph/blob/master/src/MainController.ts"
click node_algorithm_ui "https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/algorithms/sidebar/algorithm-list.tsx"
click node_algorithm_results "https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/algorithms/implementations/path-reachability/bellman-ford-a-all.tsx"
click node_layer_slice "https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/layer-slice/index.ts"
click node_import "https://github.com/raidslab/novagraph/blob/master/src/lib/InMemoryGraphManager.ts"
click node_kuzu_controller "https://github.com/raidslab/novagraph/blob/master/src/kuzu/controllers/KuzuController.ts"
click node_kuzu_service "https://github.com/raidslab/novagraph/blob/master/src/kuzu/services/KuzuBaseService.ts"
click node_query_helpers "https://github.com/raidslab/novagraph/blob/master/src/kuzu/helpers/KuzuQueryExecutor.ts"
click node_local_store "https://github.com/raidslab/novagraph/blob/master/src/kuzu/services/KuzuPersistentAsync.ts"
click node_igraph_controller "https://github.com/raidslab/novagraph/blob/master/src/igraph/IgraphController.ts"
click node_worker "https://github.com/raidslab/novagraph/blob/master/src/igraph/workers/igraph.worker.impl.ts"
click node_wasm "https://github.com/raidslab/novagraph/blob/master/src/graph.js"
click node_cypher "https://github.com/raidslab/novagraph/blob/master/src/components/ui/code-editor/index.tsx"
click node_query_output "https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/queries/query-output.tsx"
click node_compare "https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/compare/index.ts"
click node_export "https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/export/export-dropdown-button.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes,node_landing,node_visualizer,node_renderer toneBlue
class node_main,node_algorithm_ui,node_algorithm_results,node_layer_slice toneAmber
class node_import,node_kuzu_controller,node_kuzu_service,node_query_helpers,node_local_store toneMint
class node_igraph_controller,node_worker,node_wasm toneRose
class node_cypher,node_query_output,node_compare,node_export,node_user toneIndigo
```

## Components

### Presentation

- [App routes](https://github.com/raidslab/novagraph/blob/master/src/app/routes.ts): `src/app/routes.ts`
- [Landing page](https://github.com/raidslab/novagraph/blob/master/src/features/landing/index.tsx): `src/features/landing/index.tsx`
- [Visualizer UI](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/index.tsx): `src/features/visualizer/index.tsx`
- [Graph canvas](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/renderer/index.tsx): `src/features/visualizer/renderer/index.tsx`

### Orchestration

- [Main controller](https://github.com/raidslab/novagraph/blob/master/src/MainController.ts): `src/MainController.ts`
- [Algorithm selection](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/algorithms/sidebar/algorithm-list.tsx): `src/features/visualizer/algorithms/sidebar/algorithm-list.tsx`
- [Algorithm results](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/algorithms/implementations/path-reachability/bellman-ford-a-all.tsx): `src/features/visualizer/algorithms/implementations/path-reachability/bellman-ford-a-all.tsx`
- [Result encodings](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/layer-slice/index.ts): `src/features/visualizer/layer-slice/index.ts`

### Graph data

- [Graph import](https://github.com/raidslab/novagraph/blob/master/src/lib/InMemoryGraphManager.ts): `src/lib/InMemoryGraphManager.ts`
- [Kuzu controller](https://github.com/raidslab/novagraph/blob/master/src/kuzu/controllers/KuzuController.ts): `src/kuzu/controllers/KuzuController.ts`
- [Kuzu services](https://github.com/raidslab/novagraph/blob/master/src/kuzu/services/KuzuBaseService.ts): `src/kuzu/services/KuzuBaseService.ts`
- [Query helpers](https://github.com/raidslab/novagraph/blob/master/src/kuzu/helpers/KuzuQueryExecutor.ts): `src/kuzu/helpers/KuzuQueryExecutor.ts`
- [Local graph store](https://github.com/raidslab/novagraph/blob/master/src/kuzu/services/KuzuPersistentAsync.ts): `src/kuzu/services/KuzuPersistentAsync.ts`

### Analytics

- [igraph controller](https://github.com/raidslab/novagraph/blob/master/src/igraph/IgraphController.ts): `src/igraph/IgraphController.ts`
- [Analytics worker](https://github.com/raidslab/novagraph/blob/master/src/igraph/workers/igraph.worker.impl.ts): `src/igraph/workers/igraph.worker.impl.ts`
- [igraph WASM](https://github.com/raidslab/novagraph/blob/master/src/graph.js): `src/graph.js`

### Exploration tools

- [Cypher query editor](https://github.com/raidslab/novagraph/blob/master/src/components/ui/code-editor/index.tsx): `src/components/ui/code-editor/index.tsx`
- [Query results](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/queries/query-output.tsx): `src/features/visualizer/queries/query-output.tsx`
- [Result comparison](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/compare/index.ts): `src/features/visualizer/compare/index.ts`
- [Graph export](https://github.com/raidslab/novagraph/blob/master/src/features/visualizer/export/export-dropdown-button.tsx): `src/features/visualizer/export/export-dropdown-button.tsx`

### Other components

- **Analyst**

## Connections

- Analyst → App routes: opens app
- App routes → Landing page: routes to
- App routes → Visualizer UI: routes to
- Analyst → Visualizer UI: explores graph
- Visualizer UI → Main controller: uses orchestration
- Visualizer UI → Graph canvas: displays graph
- Visualizer UI → Graph import: imports graph
- Graph import → Kuzu controller: loads graph
- Main controller → Kuzu controller: controls storage (evidence: `src/MainController.ts`)
- Kuzu controller → Kuzu services: selects service (evidence: `src/kuzu/controllers/KuzuController.ts`)
- Kuzu services → Query helpers: executes queries (evidence: `src/kuzu/services/KuzuBaseService.ts`)
- Kuzu services → Local graph store: persists locally
- Visualizer UI → Algorithm selection: selects algorithms
- Algorithm selection → Main controller: requests analysis
- Main controller → igraph controller: runs analytics (evidence: `src/MainController.ts`)
- igraph controller → Analytics worker: dispatches task (evidence: `src/igraph/IgraphController.ts`)
- Analytics worker → igraph WASM: calls algorithms (evidence: `src/igraph/workers/igraph.worker.impl.ts`)
- Analytics worker → Algorithm results: returns results
- Algorithm results → Result encodings: maps result (evidence: `src/features/visualizer/algorithms/implementations/path-reachability/bellman-ford-a-all.tsx`)
- Result encodings → Graph canvas: encodes canvas
- Algorithm results → Visualizer UI: shows output
- Visualizer UI → Cypher query editor: opens optional query
- Cypher query editor → Main controller: submits query
- Main controller → Query results: returns query data
- Visualizer UI → Result comparison: compares results
- Visualizer UI → Graph export: exports graph