Star-Mapper — Graph Explorer

A high-performance Neo4j graph visualization app with Python-precomputed layouts and a Canvas 2D frontend.

Quick Start

# 1. Clone & enter the repo
git clone https://github.com/Askill/Star-Mapper.git
cd Star-Mapper

# 2. Create a virtual environment & install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Run the app
python app.py

Open http://localhost:5555 in your browser.

Environment Variables (optional)

Variable	Default	Description
NEO4J_HTTP_URL	``	Neo4j HTTP endpoint
NEO4J_USER	neo4j	Username
NEO4J_PASSWORD	(empty)	Password
NEO4J_DATABASE	neo4j	Database name

# Example: connect to a different instance
NEO4J_HTTP_URL=https://my-neo4j.example.com NEO4J_USER=admin NEO4J_PASSWORD=secret python app.py

You can also change the connection at runtime via the Connection Settings panel in the sidebar.

Features

• Neo4j connectivity via HTTP Transactional API (works behind ALB/HTTP proxies)
• Python-precomputed layouts using igraph (C-based) — auto-selects algorithm by graph size
• Canvas 2D rendering with D3 zoom/pan, quadtree hit testing, viewport frustum culling
• Curved edges with configurable curvature, multi-edge spreading
• Recursive highlight diffusion — click a node to BFS-highlight neighbors with decaying opacity
• Visual settings sliders — curvature, edge opacity/width/color, node size, label size/zoom, spacing, iterations
• Schema browser, sample queries, node search, minimap, dark glass-morphism theme

Performance

Nodes	Layout Time
300	~10 ms
3,000	~77 ms
5,000	~313 ms

---

Original Star-Mapper description below.

---

Original: Website Mapper

Star-Mapper is a Flask-based graph exploration service for Neo4j.

It provides an interactive browser UI where you can run Cypher queries, visualize large graph results, inspect schema metadata, and tune layout/visual settings in real time. Layout computation is performed server-side in Python (igraph/networkx) for better performance on larger graphs.

Current Goal

Make Neo4j graph data explorable and understandable through:

• Fast query-to-visualization workflow.
• Multiple layout algorithms with automatic selection by graph size.
• Interactive graph navigation (zoom/pan/highlight/search) plus a tabular result view.

Core Functionality

• Neo4j HTTP Transactional API integration.
• Cypher execution endpoint with graph extraction (nodes, relationships) and tabular rows.
• Server-side layout precomputation with algorithms such as:
  • auto
  • force_directed
  • force_directed_hq
  • community
  • circle
  • drl / kamada_kawai (when python-igraph is available)
  • spectral (fallback when igraph is unavailable)
• Node coloring by label and size scaling by degree.
• Client features:
  • Graph/table view toggle.
  • Hover/select neighborhood highlighting.
  • Node search and focus.
  • Minimap.
  • Visual controls (edge style, node/label size, spacing, iterations).
• Built-in demo graph generation (/api/demo) so UI can be tested without Neo4j data.

Project Structure

• app.py: Flask app and API endpoints.
• layout_engine.py: Graph layout computation and algorithm selection.
• config/sample_queries.json: Sample Cypher query definitions loaded by /api/sample-queries.
• templates/index.html: Frontend UI (canvas rendering with D3-powered interactions).
• src/Star-Mapper/: Legacy website crawler code (kept in repository, not the primary current service path).

API Endpoints

• GET /: Serves the explorer UI.
• POST /api/query: Execute Cypher and return graph + records + stats.
• GET /api/schema: Return labels, relationship types, property keys.
• GET /api/connection-test: Verify Neo4j connectivity.
• POST /api/reconnect: Update Neo4j connection settings at runtime.
• GET /api/layouts: Return available layout algorithms.
• GET /api/sample-queries: Return built-in sample Cypher queries.
• POST /api/demo: Generate synthetic graph data for demo/testing.

Configuration

Environment variables used by app.py:

• NEO4J_HTTP_URL (default: http://localhost)
• NEO4J_USER (default: neo4j)
• NEO4J_PASSWORD (default: empty)
• NEO4J_DATABASE (default: neo4j)
• SAMPLE_QUERIES_FILE (default: config/sample_queries.json)

Local Development

1. Install dependencies:

pip install -r requirements.txt

2. Optionally set Neo4j connection details:

set NEO4J_HTTP_URL=https://your-neo4j-host
set NEO4J_USER=neo4j
set NEO4J_PASSWORD=your-password
set NEO4J_DATABASE=neo4j

3. Run the app:

python app.py

4. Open:

http://localhost:5555

Notes

• The current service is the Flask app in app.py.
• Legacy crawler functionality still exists in src/Star-Mapper/main.py, but the existing web UI and API are designed for Neo4j graph exploration.