# banixx/nodges architecture

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

- Interactive diagram: https://gitdiagram.com/banixx/nodges
- Repository: https://github.com/banixx/nodges

## Overview

1. **What this repo is**
   - A client-side TypeScript/Vite application for visualizing systems in 3D, centered on exploring, filtering, and explaining graph-like data.
   - The README’s “manual, BYOK” hint and the presence of `LLMService` indicate optional user-provided AI assistance, but the core product is a local visualization tool, not a backend-driven app.

2. **Top-level runtime shape**
   - The app is a static frontend bundle built from `src/App.ts` and the modules under `src/`.
   - It ships example datasets in `public/data/**`, which act as seed content for demos and tutorials.
   - Deployment is handled as a static site pipeline via `.github/workflows/deploy.yml`.

3. **Core architecture boundary**
   - `src/core/di/ServiceContainer.ts` is the main composition root: it wires together parsing, state, rendering, interaction, and UI services.
   - The core layer is split into domain controllers rather than a single monolith, which is important for diagramming: data, state, interaction, layout, and visualization are separate subsystems.

4. **Data ingestion and normalization**
   - `DataParser` is the entry point for raw graph/data files.
   - `FileHandler`, `ImportManager`, and `DataEditor` in `src/utils` / `src/ui` handle user-facing file loading and editing.
   - The repo contains many JSON examples and archived datasets under `public/data`, suggesting a file-based data model with reusable sample inputs rather than a remote database.

5. **State and event flow**
   - `StateManager` holds the application’s canonical state; `CentralEventManager` distributes changes across subsystems.
   - `src/core/state/StateTypes.ts` and `src/core/events/EventTypes.ts` define the shared contracts between modules.
   - This is the main “control plane” boundary: UI actions and interaction events are converted into state updates, then propagated to layout, rendering, and panels.

6. **Visualization and scene management**
   - `VisualMappingEngine` translates parsed data into visual properties and mapping rules.
   - `NodeManager` and `EdgeObjectsManager` manage the rendered graph entities; these are the spatial/scene-layer managers.
   - `LayoutManager` computes spatial arrangement, likely consuming graph structure and then feeding positions back into node/edge objects.

7. **Interaction subsystem**
   - `src/core/interaction/*` contains specialized handlers for drag, hover, keyboard, selection, context menus, and node creation.
   - `InteractionManager` coordinates these handlers and sits between user input and state/scene changes.
   - This is a distinct boundary from UI panels: the panels configure behavior, while the interaction layer interprets direct manipulation in the visualization.

8. **Layout and performance execution**
   - Layout computation is offloaded through `src/workers/layout-worker.ts`, indicating that expensive graph layout work is separated from the main UI thread.
   - `PerformanceMonitor`, `PerformanceOptimizer`, and `VisualOptimizer` suggest the app is tuned for large or dense networks.
   - The `coverage/` artifacts show these areas are tested and instrumented, reinforcing that layout and rendering are key complexity hotspots.

9. **UI composition**
   - `src/ui/*` is a panel-based control surface rather than a single screen: create, file, layers, view, legend, mapping, stats, environment, minimap, info, and hover panels.
   - `UIManager` likely coordinates these widgets and binds them to application state.
   - The UI layer is largely configuration and exploration tooling around the 3D visualization core.

10. **Effects and feedback**
   - `GlowEffect` and `HighlightManager` in `src/effects` provide visual emphasis for selected, hovered, or related nodes/edges.
   - Supporting utilities like `NeighborhoodHighlighter`, `NodeLabelManager`, `EdgeLabelManager`, and `RaycastManager` bridge scene objects to interaction feedback.
   - In architecture terms, these are presentation-adjacent services that enrich the graph without changing its underlying data model.

11. **Utility and analysis services**
   - `NetworkAnalyzer`, `PathFinder`, `NodeGroupManager`, `BatchOperations`, and `SelectionManager` provide higher-level graph operations.
   - `ExportManager` supports output/export workflows, while `KeyboardShortcuts` and `ContextMenu` expose power-user control paths.
   - `LLMService` is the only clearly external-capability module; it likely supports BYOK/manual analysis assistance rather than being a required runtime dependency.

12. **Testing and quality boundaries**
   - The repo has focused unit tests for parser, layout, state, import/export, and visual mapping in `src/tests/`.
   - This matches the architecture: the most important contracts are data normalization, layout behavior, and state transitions.
   - `vitest.config.ts`, `vite.config.ts`, and the coverage reports indicate a frontend codebase with automated validation around core services.

13. **How the main data flow works**
   - Input comes from a JSON/CSV-style dataset or an imported file.
   - It is parsed and normalized, then stored in application state.
   - The visual mapping engine converts logical entities into visual descriptors.
   - Layout computes positions, workers may assist with heavy calculations, and node/edge managers update the scene.
   - Interaction and UI panels then mutate state or trigger re-layout, creating a closed loop between user action and visualization.

14. **Best way to draw the architecture**
   - Use four big boxes: **Data/Input**, **Core Services**, **Visualization/Interaction**, and **UI/Tools**.
   - Draw `ServiceContainer` and `StateManager` in the center as orchestration/state boundaries.
   - Put `layout-worker` beside the core as an off-thread compute node.
   - Show `public/data` and import/export paths as external file boundaries, and `LLMService` as an optional external integration.

Main entry points: [`src/core/di/ServiceContainer.ts`](https://github.com/banixx/nodges/blob/main/src/core/di/ServiceContainer.ts) (Service Container), [`src/core/UIManager.ts`](https://github.com/banixx/nodges/blob/main/src/core/UIManager.ts) (UI Manager), [`src/core/InteractionManager.ts`](https://github.com/banixx/nodges/blob/main/src/core/InteractionManager.ts) (Interaction Manager), [`src/core/LayoutManager.ts`](https://github.com/banixx/nodges/blob/main/src/core/LayoutManager.ts) (Layout Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["App<br/>frontend entry<br/>[App.ts]"]
end

subgraph group_data["Data/Input"]
  node_public_data[("Sample Data<br/>seed datasets")]
end

subgraph group_core["Core Services"]
  node_service_container["Service Container<br/>composition root"]
  node_data_parser["Data Parser<br/>ingestion<br/>[DataParser.ts]"]
  node_state_manager[("State Manager<br/>app state<br/>[StateManager.ts]")]
  node_event_bus(("Event Bus<br/>event distribution"))
  node_mapping_engine["Mapping Engine<br/>visual mapping"]
  node_layout_manager["Layout Manager<br/>graph layout<br/>[LayoutManager.ts]"]
  node_interaction_manager["Interaction Manager<br/>input orchestration"]
  node_ui_manager["UI Manager<br/>panel coordination<br/>[UIManager.ts]"]
end

subgraph group_viz["Visualization"]
  node_node_manager["Node Manager<br/>scene nodes<br/>[NodeManager.ts]"]
  node_edge_manager["Edge Manager<br/>scene edges"]
  node_layout_worker(("Layout Worker<br/>off-thread compute<br/>[layout-worker.ts]"))
end

subgraph group_ui["UI/Tools"]
  node_file_panel["File Panel<br/>import/export UI<br/>[FilePanelUI.ts]"]
  node_mapping_panel["Mapping Panel<br/>mapping UI<br/>[MappingUI.ts]"]
  node_view_panel["View Panel<br/>view controls<br/>[ViewPanel.ts]"]
  node_info_panel["Info Panel<br/>inspection UI<br/>[InfoPanelUI.ts]"]
  node_data_editor["Data Editor<br/>dataset editing<br/>[DataEditor.ts]"]
  node_import_manager["Import Manager<br/>file import<br/>[ImportManager.ts]"]
  node_export_manager["Export Manager<br/>file export<br/>[ExportManager.ts]"]
  node_llm_service["LLM Service<br/>optional AI<br/>[LLMService.ts]"]
end

node_app -->|"bootstraps"| node_service_container
node_service_container -->|"wires"| node_data_parser
node_service_container -->|"wires"| node_state_manager
node_service_container -->|"wires"| node_event_bus
node_service_container -->|"wires"| node_mapping_engine
node_service_container -->|"wires"| node_layout_manager
node_service_container -->|"wires"| node_node_manager
node_service_container -->|"wires"| node_edge_manager
node_service_container -->|"wires"| node_interaction_manager
node_service_container -->|"wires"| node_ui_manager
node_public_data -->|"loads"| node_import_manager
node_import_manager -->|"parses"| node_data_parser
node_file_panel -->|"triggers"| node_import_manager
node_file_panel -->|"triggers"| node_export_manager
node_data_editor -->|"edits"| node_state_manager
node_state_manager -->|"publishes"| node_event_bus
node_event_bus -->|"updates"| node_mapping_engine
node_event_bus -->|"updates"| node_layout_manager
node_layout_manager -->|"offloads"| node_layout_worker
node_layout_manager -->|"positions"| node_node_manager
node_layout_manager -->|"positions"| node_edge_manager
node_mapping_engine -->|"styles"| node_node_manager
node_mapping_engine -->|"styles"| node_edge_manager
node_interaction_manager -->|"emits"| node_event_bus
node_interaction_manager -->|"mutates"| node_state_manager
node_ui_manager -->|"hosts"| node_view_panel
node_ui_manager -->|"hosts"| node_mapping_panel
node_ui_manager -->|"hosts"| node_info_panel
node_ui_manager -->|"hosts"| node_file_panel
node_ui_manager -->|"hosts"| node_data_editor
node_ui_manager -.->|"optionally uses"| node_llm_service
node_ui_manager -->|"configures"| node_interaction_manager
node_interaction_manager -->|"targets"| node_node_manager
node_interaction_manager -->|"targets"| node_edge_manager

click node_app "https://github.com/banixx/nodges/blob/main/src/App.ts"
click node_service_container "https://github.com/banixx/nodges/blob/main/src/core/di/ServiceContainer.ts"
click node_data_parser "https://github.com/banixx/nodges/blob/main/src/core/DataParser.ts"
click node_state_manager "https://github.com/banixx/nodges/blob/main/src/core/StateManager.ts"
click node_event_bus "https://github.com/banixx/nodges/blob/main/src/core/CentralEventManager.ts"
click node_mapping_engine "https://github.com/banixx/nodges/blob/main/src/core/VisualMappingEngine.ts"
click node_layout_manager "https://github.com/banixx/nodges/blob/main/src/core/LayoutManager.ts"
click node_node_manager "https://github.com/banixx/nodges/blob/main/src/core/NodeManager.ts"
click node_edge_manager "https://github.com/banixx/nodges/blob/main/src/core/EdgeObjectsManager.ts"
click node_interaction_manager "https://github.com/banixx/nodges/blob/main/src/core/InteractionManager.ts"
click node_layout_worker "https://github.com/banixx/nodges/blob/main/src/workers/layout-worker.ts"
click node_ui_manager "https://github.com/banixx/nodges/blob/main/src/core/UIManager.ts"
click node_file_panel "https://github.com/banixx/nodges/blob/main/src/ui/FilePanelUI.ts"
click node_mapping_panel "https://github.com/banixx/nodges/blob/main/src/ui/MappingUI.ts"
click node_view_panel "https://github.com/banixx/nodges/blob/main/src/ui/ViewPanel.ts"
click node_info_panel "https://github.com/banixx/nodges/blob/main/src/ui/InfoPanelUI.ts"
click node_data_editor "https://github.com/banixx/nodges/blob/main/src/ui/DataEditor.ts"
click node_import_manager "https://github.com/banixx/nodges/blob/main/src/utils/ImportManager.ts"
click node_export_manager "https://github.com/banixx/nodges/blob/main/src/utils/ExportManager.ts"
click node_llm_service "https://github.com/banixx/nodges/blob/main/src/utils/LLMService.ts"
click node_public_data "https://github.com/banixx/nodges/tree/main/public/data"

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_app toneBlue
class node_public_data toneAmber
class node_service_container,node_data_parser,node_state_manager,node_event_bus,node_mapping_engine,node_layout_manager,node_interaction_manager,node_ui_manager toneMint
class node_node_manager,node_edge_manager,node_layout_worker toneRose
class node_file_panel,node_mapping_panel,node_view_panel,node_info_panel,node_data_editor,node_import_manager,node_export_manager,node_llm_service toneIndigo
```

## Components

### Runtime

Static Vite frontend and build/deploy entrypoints

- [App](https://github.com/banixx/nodges/blob/main/src/App.ts): frontend entry · Top-level client application bootstrap · `src/App.ts`

### Data/Input

Example datasets and file import/edit entrypoints

- [Sample Data](https://github.com/banixx/nodges/tree/main/public/data): seed datasets · Bundled example and archived graph datasets · `public/data`

### Core Services

Composition root, state, parsing, mapping, layout, and scene services

- [Service Container](https://github.com/banixx/nodges/blob/main/src/core/di/ServiceContainer.ts): composition root · Wires together the application subsystems · `src/core/di/ServiceContainer.ts`
- [Data Parser](https://github.com/banixx/nodges/blob/main/src/core/DataParser.ts): ingestion · Normalizes raw graph/data files into internal structures · `src/core/DataParser.ts`
- [State Manager](https://github.com/banixx/nodges/blob/main/src/core/StateManager.ts): app state · Canonical application state and update coordination · `src/core/StateManager.ts`
- [Event Bus](https://github.com/banixx/nodges/blob/main/src/core/CentralEventManager.ts): event distribution · Shared event contracts and central propagation · `src/core/CentralEventManager.ts`
- [Mapping Engine](https://github.com/banixx/nodges/blob/main/src/core/VisualMappingEngine.ts): visual mapping · Converts logical data into visual properties · `src/core/VisualMappingEngine.ts`
- [Layout Manager](https://github.com/banixx/nodges/blob/main/src/core/LayoutManager.ts): graph layout · Computes spatial arrangement for nodes and edges · `src/core/LayoutManager.ts`
- [Interaction Manager](https://github.com/banixx/nodges/blob/main/src/core/InteractionManager.ts): input orchestration · Coordinates drag, hover, selection, and keyboard input · `src/core/InteractionManager.ts`
- [UI Manager](https://github.com/banixx/nodges/blob/main/src/core/UIManager.ts): panel coordination · Coordinates the application control surface · `src/core/UIManager.ts`

### Visualization

Rendered graph objects, effects, and off-thread layout

- [Node Manager](https://github.com/banixx/nodges/blob/main/src/core/NodeManager.ts): scene nodes · Creates and updates rendered node objects · `src/core/NodeManager.ts`
- [Edge Manager](https://github.com/banixx/nodges/blob/main/src/core/EdgeObjectsManager.ts): scene edges · Creates and updates rendered edge objects · `src/core/EdgeObjectsManager.ts`
- [Layout Worker](https://github.com/banixx/nodges/blob/main/src/workers/layout-worker.ts): off-thread compute · Worker for expensive layout calculations · `src/workers/layout-worker.ts`

### UI/Tools

Panels and user-facing tools around the visualization

- [File Panel](https://github.com/banixx/nodges/blob/main/src/ui/FilePanelUI.ts): import/export UI · File loading and dataset switching controls · `src/ui/FilePanelUI.ts`
- [Mapping Panel](https://github.com/banixx/nodges/blob/main/src/ui/MappingUI.ts): mapping UI · Controls visual mapping rules and adjustments · `src/ui/MappingUI.ts`
- [View Panel](https://github.com/banixx/nodges/blob/main/src/ui/ViewPanel.ts): view controls · Camera, scene, and visualization options · `src/ui/ViewPanel.ts`
- [Info Panel](https://github.com/banixx/nodges/blob/main/src/ui/InfoPanelUI.ts): inspection UI · Displays details for selected or hovered items · `src/ui/InfoPanelUI.ts`
- [Data Editor](https://github.com/banixx/nodges/blob/main/src/ui/DataEditor.ts): dataset editing · Inline editing of structured input data · `src/ui/DataEditor.ts`
- [Import Manager](https://github.com/banixx/nodges/blob/main/src/utils/ImportManager.ts): file import · User-facing import workflow for datasets · `src/utils/ImportManager.ts`
- [Export Manager](https://github.com/banixx/nodges/blob/main/src/utils/ExportManager.ts): file export · Exports graph state and derived outputs · `src/utils/ExportManager.ts`
- [LLM Service](https://github.com/banixx/nodges/blob/main/src/utils/LLMService.ts): optional AI · Optional user-provided AI assistance integration · `src/utils/LLMService.ts`

## Connections

- App → Service Container: bootstraps · App starts the composed service graph
- Service Container → Data Parser: wires · Provides parsing services
- Service Container → State Manager: wires · Provides canonical application state
- Service Container → Event Bus: wires · Connects shared event propagation
- Service Container → Mapping Engine: wires · Connects visual mapping
- Service Container → Layout Manager: wires · Connects layout computation
- Service Container → Node Manager: wires · Connects scene node management
- Service Container → Edge Manager: wires · Connects scene edge management
- Service Container → Interaction Manager: wires · Connects user input orchestration
- Service Container → UI Manager: wires · Connects the control surface
- Sample Data → Import Manager: loads · Seed datasets can be imported into the app
- Import Manager → Data Parser: parses · Imported files are normalized by the parser
- File Panel → Import Manager: triggers · File UI starts import workflows
- File Panel → Export Manager: triggers · File UI starts export workflows
- Data Editor → State Manager: edits · Editing mutates canonical state
- State Manager → Event Bus: publishes · State changes are broadcast to the rest of the app
- Event Bus → Mapping Engine: updates · Mapping reacts to state and data changes
- Event Bus → Layout Manager: updates · Layout reacts to graph or setting changes
- Layout Manager → Layout Worker: offloads · Heavy layout computation moves to worker thread
- Layout Manager → Node Manager: positions · Computed positions drive node placement
- Layout Manager → Edge Manager: positions · Layout feeds edge geometry and routing
- Mapping Engine → Node Manager: styles · Visual mapping defines node appearance
- Mapping Engine → Edge Manager: styles · Visual mapping defines edge appearance
- Interaction Manager → Event Bus: emits · Input events are translated into app events
- Interaction Manager → State Manager: mutates · Selection, drag, and creation update state
- UI Manager → View Panel: hosts · Coordinates the view controls
- UI Manager → Mapping Panel: hosts · Coordinates visual mapping controls
- UI Manager → Info Panel: hosts · Coordinates inspection panels
- UI Manager → File Panel: hosts · Coordinates file and dataset actions
- UI Manager → Data Editor: hosts · Coordinates editing tools
- UI Manager → LLM Service: optionally uses · Optional BYOK analysis assistance
- UI Manager → Interaction Manager: configures · Panels can adjust interaction behavior
- Interaction Manager → Node Manager: targets · Direct manipulation acts on rendered nodes
- Interaction Manager → Edge Manager: targets · Interaction can affect connected edges