Star-Mapper/README.md

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

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