How bevel-software/bevel-neo4j-viz works
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