How ejagombar/wikimapper works
1. Repository shape
WikiMapper is split into a native C++ desktop client and a small Go server. The client is the main product: it loads Wikipedia graph data, simulates the layout, and renders an interactive 3D scene. The server side appears to be a deployable HTTP service used to talk to the backing graph database.
2. Top-level runtime boundary
The core app is a C++20/OpenGL program built with CMake. It runs as a GUI desktop application with its own render loop, input handling, and background simulation. That makes the main architecture split between:
- local interactive visualization and physics in the client
- remote data access via the server/database boundary
3. Data source and ingestion
Wikipedia relationship data is not embedded in the renderer; it is fetched through a database layer, likely backed by Neo4j as described in the README. src/graphLoader.cpp is the bridge that turns external responses into internal graph state. The server/ Go service likely exists to expose that graph data over HTTP and is packaged as a system service via the included service file and setup script.
4. Graph model subsystem
src/graph.cpp, src/graph.hpp, and related files define the in-memory graph representation: nodes, edges, selection state, and likely spatial/query helpers. This is the central model shared by simulation, UI, and rendering. src/pointMaths.* supports geometric operations used by layout and visual placement.
5. Physics / layout simulation
src/simulation.cpp runs the force-directed layout engine. The README calls out a dedicated physics thread, so the layout evolves independently of rendering. This subsystem is responsible for node repulsion/attraction, movement smoothing, and likely stabilization/oscillation detection before state is handed to the renderer.
6. Threading and state exchange
A key architectural boundary is the triple-buffered handoff between simulation and rendering. The simulation thread produces updated graph positions while the render thread consumes a consistent snapshot without blocking. lib/mutex_guarded.hpp and src/controlPlane.* suggest additional synchronization and coordination around shared app state and user actions.
7. Rendering engine
src/visual/engine.cpp is the OpenGL owner: window/context setup, frame submission, and orchestration of visual passes. The README highlights modern rendering techniques such as instancing, impostor geometry, UBOs, and framebuffer-based post-processing. The src/visual/* modules are organized by renderable concerns rather than by scene level.
8. Visual subsystems
The visual folder is broken into focused components:
- camera for 3D navigation and view/projection matrices
- shader, texture, uniformBufferObject for GPU resource management
- skybox, bloom, filter for environment and post-processing
- label, text for node labels and text rendering
- selector for hover/selection feedback
- gui for ImGui integration
This suggests a layered render pipeline where scene objects, text, and UI are composited into the final frame.
9. Shader and asset pipeline
The shaders/ directory contains the GPU programs for each render pass: spheres, cylinders, labels, skybox, bloom, and framebuffer effects. The asset folder includes benchmark datasets and timestamps, indicating the project has performance-focused test inputs and probably uses them to validate large graph behavior.
10. Interaction and control flow
User input enters through the interface layer (src/interface.*) and the GUI layer (src/visual/gui.*). Commands like camera movement, node selection, double-click expansion, and search are mapped to graph actions and scene updates. src/controlPlane.* appears to coordinate these higher-level actions, keeping UI events separate from simulation and rendering mechanics.
11. Search / utility subsystem
lib/ImSearch is a local search helper used for fast article lookup and navigation within the graph. The bundled utility headers (json.hpp, base64.hpp, rgb_hsv.*, std_image.h) indicate the repo vendors a few small dependencies for parsing, encoding, color conversion, and image handling rather than relying entirely on the system.
12. Server deployment
The server/ directory is a separate Go module with its own deployment artifacts. That implies the architecture can be deployed with a long-lived backend service, while the C++ client remains a standalone GUI application. The server is likely the only network-facing component; the visualizer itself is primarily an offline/interactive frontend once data is loaded.
13. How the pieces fit together
The main end-to-end flow is: Wikipedia graph data is fetched through the server/database boundary, loaded into the graph model, fed into the physics simulation thread, exchanged via buffered shared state, and finally rendered by the OpenGL engine with UI overlays and selection feedback. The architecture is optimized for interactive exploration of large 3D graphs rather than for general-purpose UI or web delivery.
Main entry points: engine.cpp Engine · controlPlane.cpp Control · application.cpp Runtime · graphLoader.cpp Loader
Components 19
C++ client
Desktop application for loading, simulating, and rendering Wikipedia graphs.
- App · Main client startup and application lifecycle.
src/main.cpp - Runtime · Owns high-level app wiring and top-level coordination.
src/application.cpp - Control · Coordinates user actions, state changes, and subsystem interactions.
src/controlPlane.cpp - Input · Bridges user input into application commands.
src/interface.cpp - Loader · Converts external graph responses into internal model state.
src/graphLoader.cpp - Simulation · Force-directed layout engine running on its own thread.
src/simulation.cpp
Go server
HTTP backend that serves graph data and deploys as a service.
Shared code
Reusable libraries and model code used across client subsystems.
- Graph · Core graph state: nodes, edges, selection, and queryable layout data.
src/graph.cpp - Math · Point and spatial math used by layout and placement.
src/pointMaths.cpp - State sync · Shared-state synchronization and guarded access utilities.
lib/mutex_guarded.hpp - Search · Fast local article lookup and navigation support.
lib/ImSearch/imsearch.cpp - Benchmarks · Benchmark tracks and timestamps for performance-focused testing.
assets/benchmarkTimestamps
Rendering
OpenGL scene, visual effects, and GPU resource management.
- Engine · OpenGL window/context ownership and frame orchestration.
src/visual/engine.cpp - Camera · 3D navigation and view/projection management.
src/visual/camera.cpp - Scene · Scene rendering for graph primitives and composition.
src/visual/label.cpp - Effects · Bloom, filtering, skybox, selection, and other visual passes.
src/visual/bloom.cpp - UI · ImGui overlay and on-screen controls.
src/visual/gui.cpp - Shaders · Shader sources for graph primitives, labels, UI, and post-processing.
shaders/sphere.vert
Connections 20
- App → Runtime: starts · Main entry initializes the application runtime.
- Runtime → Control: orchestrates · Top-level runtime delegates coordination to the control plane.
- Control → Input: receives input · User events are translated into app actions.
- Control → Loader: loads data · Coordinates graph acquisition and model population.
- Loader → Server: fetches · Client obtains graph data through the backend service.
- Server → Deploy: packs · Server is configured for service deployment.
- Loader → Graph: builds · External responses become internal graph state.
- Graph → Math: uses · Geometry helpers support layout and placement.
- Graph → Simulation: feeds · Simulation consumes current graph state.
- Simulation → State sync: syncs · Simulation writes through guarded shared state.
- State sync → Engine: publishes · Renderer reads consistent snapshots without blocking.
- Engine → Camera: drives view · Render loop applies camera matrices and navigation state.
- Engine → Scene: renders · Core draw calls submit graph scene primitives.
- Engine → Effects: composes · Post-processing and overlays are layered into the final frame.
- Engine → UI: overlays · GUI is composited on top of the 3D scene.
- Scene → Shaders: uses · Scene rendering depends on specialized GPU programs.
- Effects → Shaders: uses · Visual passes are implemented by shader programs.
- UI → Search: supports · Interactive lookup helps navigate large graphs.
- Control → Search: invokes · Search is exposed through higher-level user actions.
- Runtime → Benchmarks: benchmarks · Benchmark datasets support performance evaluation.