banixx/nodges

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.