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