# bevel-software/bevel-neo4j-viz architecture

> Architecture diagram of the GitHub repository bevel-software/bevel-neo4j-viz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bevel-software/bevel-neo4j-viz
- Repository: https://github.com/bevel-software/bevel-neo4j-viz

## Overview

##### Project Type & Purpose
- This is a VS Code extension (“Bevel Neo4j Visualization”) written in TypeScript, with an embedded React‐based webview UI.
- Purpose: export or query Neo4j graph data (either from Bevel’s internal knowledge graphs or any external Neo4j database), then render interactive graph visualizations and AI‐powered Cypher query assistance directly in VS Code.

##### High‐Level Architecture Layers
a. VS Code Extension Host (NodeJS process)
b. Embedded Webview Front-end (React + NVL)
c. External Services
- Bevel Software Extension API
- Neo4j Database

##### Main Components
A. Extension Host Layer
1. extension.ts
– Activation entrypoint; registers commands and providers.
2. CommandManager (src/commands)
– Centralizes handling of VS Code commands (e.g., “Open Neo4j Visualization,” “Execute Cypher”).
3. Providers
– BevelCodeLensProvider: injects CodeLens items into the editor.
– TabWebviewProvider: creates and manages the webview panel.
4. Services (src/services)
a. BevelClientService: interacts with the main Bevel extension’s API to retrieve the code knowledge graph.
b. Neo4jService & subcomponents (ConnectionManager, CypherGenerator, ProjectExporter, QueryExecutor): manage connection lifecycle, export data, generate Cypher, and run queries.
5. Domain & Utils
– WebviewCommunicationInterface/WebviewMessage: typed messages exchanged over postMessage.
– Logger, Neo4jConfigService, ServiceManager, getNonce/getUri, hover utilities.

B. Webview (tab-webview)
1. React App (App.tsx)
2. UI Components:
- ConnectionForm, CypherValidator, QueryAssistant, QueryPanel
- GraphView & Neo4jVisualization (NVL integration)
- NodePropertiesPanel, styled visualization elements, hooks for simulation/layout/interactions
3. Messaging Bridge (useVSCodeMessaging hook)
– Sends user actions (connect, export, run query, AI prompt) as messages to the Extension Host.
– Listens for responses (query results, export status, AI‐generated Cypher).

C. External Systems
1. Bevel Software VS Code Extension (required for “Bevel API Mode”)
2. Neo4j Database (Bolt or Neo4j+ protocol)

##### Component Interactions & Data Flow
1. User invokes “Open Neo4j Visualization” → CommandManager calls TabWebviewProvider → webview panel opens.
2. Webview UI → sends “connect” message (with URI/credentials + mode) → Extension Host → Neo4jService.ConnectionManager establishes DB session.
3. In Bevel API Mode:
a. User triggers “Export Project” → Extension Host → BevelClientService pulls knowledge graph → ProjectExporter loads nodes/rels into Neo4jService.
4. Query Execution:
a. User types Cypher or AI prompt → Webview sends “executeQuery” or “generateQuery” → Extension Host invokes QueryExecutor or CypherGenerator → results returned → Webview renders graph via NVL.
5. Node click in graph → Webview fires event → Extension Host logs or shows hover/info via hover.ts utilities.

##### Architectural Patterns & Design Principles
- Command Pattern: CommandManager abstracts VS Code commands.
- Provider Pattern: Webview and CodeLens providers integrate with VS Code’s extension points.
- Service Layer: encapsulates external interactions (Bevel API, Neo4j DB).
- Message Bus (postMessage): decouples UI from backend logic via well‐typed messages.
- Separation of Concerns:
- Domain interfaces define message contracts.
- Utils handle cross‐cutting concerns (logging, config).
- UI code is pure React + hooks, unaware of VS Code internals beyond messaging.

##### Technologies & Frameworks
- VS Code Extension API, TypeScript, Node.js
- React, NVL (Neo4j Visualization Library), Webview
- Neo4j JavaScript Driver, Cypher
- Esbuild (build script), Jest (testing), ESLint

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "VS Code Extension Host"
    ext["extension.ts"]:::core
    cmd["CommandManager"]:::core
    codeLens["BevelCodeLensProvider"]:::core
    tabProv["TabWebviewProvider"]:::core
    subgraph Services
      bevelClient["BevelClientService"]:::service
      neo4jSvc["Neo4jService"]:::service
      connMgr["ConnectionManager"]:::service
      cyphGen["CypherGenerator"]:::service
      projExp["ProjectExporter"]:::service
      queryExec["QueryExecutor"]:::service
    end
    subgraph "Domain & Utils"
      wci["WebviewCommunicationInterface"]:::core
      wm["WebviewMessage"]:::core
      logger["Logger"]:::core
      cfgSvc["Neo4jConfigService"]:::core
      svcMgr["ServiceManager"]:::core
      nonce["getNonce"]:::core
      uri["getUri"]:::core
      hover["hover utils"]:::core
    end
    ext --> cmd
    ext --> codeLens
    ext --> tabProv
    cmd --> tabProv
    tabProv --> wci
    tabProv --> wm
    bevelClient --> neo4jSvc
    neo4jSvc --> connMgr
    neo4jSvc --> cyphGen
    neo4jSvc --> projExp
    neo4jSvc --> queryExec
  end

  subgraph "Webview Front-end"
    app["App.tsx"]:::ui
    cf["ConnectionForm"]:::ui
    cv["CypherValidator"]:::ui
    qa["QueryAssistant"]:::ui
    qp["QueryPanel"]:::ui
    gv["GraphView"]:::ui
    nv["Neo4jVisualization"]:::ui
    np["NodePropertiesPanel"]:::ui
    styled["styled visualization"]:::ui
    subgraph "NVL Hooks"
      sim["useNvlForceSimulation"]:::ui
      inst["useNvlInstance"]:::ui
      inter["useNvlInteractions"]:::ui
      layout["useNvlLayout"]:::ui
      uiHook["useNvlUI"]:::ui
    end
    msgHook["useVSCodeMessaging"]:::ui
    app --> cf
    app --> cv
    app --> qa
    app --> qp
    app --> gv
    app --> nv
    gv --> np
    gv --> styled
    gv --> sim
    gv --> inst
    gv --> inter
    gv --> layout
    gv --> uiHook
    app --> msgHook
  end

  subgraph "External Services"
    bevelAPI["Bevel Extension API"]:::external
    neo4jDB["Neo4j Database"]:::external
  end

  %% Data flows
  cf -->|connect| msgHook
  msgHook -.->|postMessage| wci
  wci --> connMgr
  projExp --> neo4jDB
  queryExec --> neo4jDB
  cyphGen --> neo4jDB
  bevelClient --> bevelAPI
  msgHook -.->|executeQuery/generateQuery| queryExec
  queryExec --> msgHook
  cyphGen --> msgHook
  connMgr --> msgHook

  %% Click Events
  click ext "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/extension.ts"
  click cmd "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/commands/CommandManager.ts"
  click codeLens "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/providers/BevelCodeLensProvider.ts"
  click tabProv "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/providers/TabWebviewProvider.ts"
  click bevelClient "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/services/BevelClientService.ts"
  click neo4jSvc "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/services/neo4j/Neo4jService.ts"
  click connMgr "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/services/neo4j/ConnectionManager.ts"
  click cyphGen "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/services/neo4j/CypherGenerator.ts"
  click projExp "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/services/neo4j/ProjectExporter.ts"
  click queryExec "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/services/neo4j/QueryExecutor.ts"
  click wci "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/domain/WebviewCommunicationInterface.ts"
  click wm "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/domain/WebviewMessage.ts"
  click logger "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/utils/Logger.ts"
  click cfgSvc "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/utils/Neo4jConfigService.ts"
  click svcMgr "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/utils/ServiceManager.ts"
  click nonce "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/utils/getNonce.ts"
  click uri "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/utils/getUri.ts"
  click hover "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/src/utils/hover.ts"
  click msgHook "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/utils/useVSCodeMessaging.ts"
  click app "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/App.tsx"
  click cf "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/ConnectionForm.tsx"
  click cv "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/CypherValidator.tsx"
  click qa "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/QueryAssistant.tsx"
  click qp "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/QueryPanel.tsx"
  click gv "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/GraphView.tsx"
  click nv "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/Neo4jVisualization.tsx"
  click np "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/visualization/NodePropertiesPanel.tsx"
  click styled "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/visualization/styled.ts"
  click sim "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/visualization/hooks/useNvlForceSimulation.ts"
  click inst "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/visualization/hooks/useNvlInstance.ts"
  click inter "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/visualization/hooks/useNvlInteractions.ts"
  click layout "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/visualization/hooks/useNvlLayout.ts"
  click uiHook "https://github.com/bevel-software/bevel-neo4j-viz/blob/main/tab-webview/src/components/visualization/hooks/useNvlUI.ts"

  classDef core fill:#ADD8E6,stroke:#000
  classDef service fill:#90EE90,stroke:#000
  classDef ui fill:#FFA500,stroke:#000
  classDef external fill:#D3D3D3,stroke:#000
```
