Star-Mapper/README.md

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