155 lines
4.9 KiB
Markdown
155 lines
4.9 KiB
Markdown
# Star-Mapper — Cortex Graph Explorer
|
|
|
|
A high-performance Neo4j graph visualization app with Python-precomputed layouts and a Canvas 2D frontend.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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` | `https://neo4j.develop.cortex.cloud.otto.de` | Neo4j HTTP endpoint |
|
|
| `NEO4J_USER` | `neo4j` | Username |
|
|
| `NEO4J_PASSWORD` | _(empty)_ | Password |
|
|
| `NEO4J_DATABASE` | `neo4j` | Database name |
|
|
|
|
```bash
|
|
# 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.
|
|
- `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`)
|
|
|
|
## Local Development
|
|
|
|
1. Install dependencies:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
2. Optionally set Neo4j connection details:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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. |