# ejagombar/wikimapper architecture

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

- Interactive diagram: https://gitdiagram.com/ejagombar/wikimapper
- Repository: https://github.com/ejagombar/wikimapper

## Overview

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: [`src/visual/engine.cpp`](https://github.com/ejagombar/wikimapper/blob/main/src/visual/engine.cpp) (Engine), [`src/controlPlane.cpp`](https://github.com/ejagombar/wikimapper/blob/main/src/controlPlane.cpp) (Control), [`src/application.cpp`](https://github.com/ejagombar/wikimapper/blob/main/src/application.cpp) (Runtime), [`src/graphLoader.cpp`](https://github.com/ejagombar/wikimapper/blob/main/src/graphLoader.cpp) (Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["C++ client"]
  node_app["App<br/>desktop entry<br/>[main.cpp]"]
  node_application["Runtime<br/>app shell<br/>[application.cpp]"]
  node_control["Control<br/>coordination<br/>[controlPlane.cpp]"]
  node_interface["Input<br/>event layer<br/>[interface.cpp]"]
  node_loader["Loader<br/>ingest bridge<br/>[graphLoader.cpp]"]
  node_sim(("Simulation<br/>physics layout<br/>[simulation.cpp]"))
end

subgraph group_server["Go server"]
  node_servermain["Server<br/>http service<br/>[main.go]"]
  node_deploy["Deploy<br/>service setup"]
end

subgraph group_shared["Shared code"]
  node_graph[("Graph<br/>in-memory model<br/>[graph.cpp]")]
  node_maths(("Math<br/>geometry utils<br/>[pointMaths.cpp]"))
  node_guard(("State sync<br/>thread sync<br/>[mutex_guarded.hpp]"))
  node_search["Search<br/>lookup helper<br/>[imsearch.cpp]"]
  node_assets["Benchmarks<br/>data assets"]
end

subgraph group_render["Rendering"]
  node_engine["Engine<br/>render loop<br/>[engine.cpp]"]
  node_camera(("Camera<br/>view control<br/>[camera.cpp]"))
  node_scene["Scene<br/>drawables<br/>[label.cpp]"]
  node_effects["Effects<br/>postprocess<br/>[bloom.cpp]"]
  node_ui["UI<br/>overlay<br/>[gui.cpp]"]
  node_shaders["Shaders<br/>gpu programs<br/>[sphere.vert]"]
end

node_app -->|"starts"| node_application
node_application -->|"orchestrates"| node_control
node_control -->|"receives input"| node_interface
node_control -->|"loads data"| node_loader
node_loader -->|"fetches"| node_servermain
node_servermain -.->|"packs"| node_deploy
node_loader -->|"builds"| node_graph
node_graph -->|"uses"| node_maths
node_graph -->|"feeds"| node_sim
node_sim -->|"syncs"| node_guard
node_guard -->|"publishes"| node_engine
node_engine -->|"drives view"| node_camera
node_engine -->|"renders"| node_scene
node_engine -->|"composes"| node_effects
node_engine -->|"overlays"| node_ui
node_scene -->|"uses"| node_shaders
node_effects -->|"uses"| node_shaders
node_ui -->|"supports"| node_search
node_control -->|"invokes"| node_search
node_application -.->|"benchmarks"| node_assets

click node_app "https://github.com/ejagombar/wikimapper/blob/main/src/main.cpp"
click node_application "https://github.com/ejagombar/wikimapper/blob/main/src/application.cpp"
click node_control "https://github.com/ejagombar/wikimapper/blob/main/src/controlPlane.cpp"
click node_interface "https://github.com/ejagombar/wikimapper/blob/main/src/interface.cpp"
click node_loader "https://github.com/ejagombar/wikimapper/blob/main/src/graphLoader.cpp"
click node_graph "https://github.com/ejagombar/wikimapper/blob/main/src/graph.cpp"
click node_maths "https://github.com/ejagombar/wikimapper/blob/main/src/pointMaths.cpp"
click node_sim "https://github.com/ejagombar/wikimapper/blob/main/src/simulation.cpp"
click node_guard "https://github.com/ejagombar/wikimapper/blob/main/lib/mutex_guarded.hpp"
click node_engine "https://github.com/ejagombar/wikimapper/blob/main/src/visual/engine.cpp"
click node_camera "https://github.com/ejagombar/wikimapper/blob/main/src/visual/camera.cpp"
click node_scene "https://github.com/ejagombar/wikimapper/blob/main/src/visual/label.cpp"
click node_effects "https://github.com/ejagombar/wikimapper/blob/main/src/visual/bloom.cpp"
click node_ui "https://github.com/ejagombar/wikimapper/blob/main/src/visual/gui.cpp"
click node_shaders "https://github.com/ejagombar/wikimapper/blob/main/shaders/sphere.vert"
click node_search "https://github.com/ejagombar/wikimapper/blob/main/lib/ImSearch/imsearch.cpp"
click node_servermain "https://github.com/ejagombar/wikimapper/blob/main/server/main.go"
click node_deploy "https://github.com/ejagombar/wikimapper/blob/main/server/wikimapper-server.service"
click node_assets "https://github.com/ejagombar/wikimapper/tree/main/assets/benchmarkTimestamps"

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,node_application,node_control,node_interface,node_loader,node_sim toneBlue
class node_servermain,node_deploy toneAmber
class node_graph,node_maths,node_guard,node_search,node_assets toneMint
class node_engine,node_camera,node_scene,node_effects,node_ui,node_shaders toneRose
```

## Components

### C++ client

Desktop application for loading, simulating, and rendering Wikipedia graphs.

- [App](https://github.com/ejagombar/wikimapper/blob/main/src/main.cpp): desktop entry · Main client startup and application lifecycle. · `src/main.cpp`
- [Runtime](https://github.com/ejagombar/wikimapper/blob/main/src/application.cpp): app shell · Owns high-level app wiring and top-level coordination. · `src/application.cpp`
- [Control](https://github.com/ejagombar/wikimapper/blob/main/src/controlPlane.cpp): coordination · Coordinates user actions, state changes, and subsystem interactions. · `src/controlPlane.cpp`
- [Input](https://github.com/ejagombar/wikimapper/blob/main/src/interface.cpp): event layer · Bridges user input into application commands. · `src/interface.cpp`
- [Loader](https://github.com/ejagombar/wikimapper/blob/main/src/graphLoader.cpp): ingest bridge · Converts external graph responses into internal model state. · `src/graphLoader.cpp`
- [Simulation](https://github.com/ejagombar/wikimapper/blob/main/src/simulation.cpp): physics layout · 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.

- [Server](https://github.com/ejagombar/wikimapper/blob/main/server/main.go): http service · Go service entrypoint for remote graph access. · `server/main.go`
- [Deploy](https://github.com/ejagombar/wikimapper/blob/main/server/wikimapper-server.service): service setup · System service and setup scripts for server deployment. · `server/wikimapper-server.service`

### Shared code

Reusable libraries and model code used across client subsystems.

- [Graph](https://github.com/ejagombar/wikimapper/blob/main/src/graph.cpp): in-memory model · Core graph state: nodes, edges, selection, and queryable layout data. · `src/graph.cpp`
- [Math](https://github.com/ejagombar/wikimapper/blob/main/src/pointMaths.cpp): geometry utils · Point and spatial math used by layout and placement. · `src/pointMaths.cpp`
- [State sync](https://github.com/ejagombar/wikimapper/blob/main/lib/mutex_guarded.hpp): thread sync · Shared-state synchronization and guarded access utilities. · `lib/mutex_guarded.hpp`
- [Search](https://github.com/ejagombar/wikimapper/blob/main/lib/ImSearch/imsearch.cpp): lookup helper · Fast local article lookup and navigation support. · `lib/ImSearch/imsearch.cpp`
- [Benchmarks](https://github.com/ejagombar/wikimapper/tree/main/assets/benchmarkTimestamps): data assets · Benchmark tracks and timestamps for performance-focused testing. · `assets/benchmarkTimestamps`

### Rendering

OpenGL scene, visual effects, and GPU resource management.

- [Engine](https://github.com/ejagombar/wikimapper/blob/main/src/visual/engine.cpp): render loop · OpenGL window/context ownership and frame orchestration. · `src/visual/engine.cpp`
- [Camera](https://github.com/ejagombar/wikimapper/blob/main/src/visual/camera.cpp): view control · 3D navigation and view/projection management. · `src/visual/camera.cpp`
- [Scene](https://github.com/ejagombar/wikimapper/blob/main/src/visual/label.cpp): drawables · Scene rendering for graph primitives and composition. · `src/visual/label.cpp`
- [Effects](https://github.com/ejagombar/wikimapper/blob/main/src/visual/bloom.cpp): postprocess · Bloom, filtering, skybox, selection, and other visual passes. · `src/visual/bloom.cpp`
- [UI](https://github.com/ejagombar/wikimapper/blob/main/src/visual/gui.cpp): overlay · ImGui overlay and on-screen controls. · `src/visual/gui.cpp`
- [Shaders](https://github.com/ejagombar/wikimapper/blob/main/shaders/sphere.vert): gpu programs · Shader sources for graph primitives, labels, UI, and post-processing. · `shaders/sphere.vert`

## Connections

- 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.
