StoneLink

A real-time operational analytics platform for mining and aggregate processing networks. Visualize equipment relationships, simulate faults, and understand cascading impacts across your supply chain with two-tier impact analysis.

Deployment: https://stonelink.onrender.com

Features

✨ Visual Graph Analytics

• Interactive Cytoscape.js visualization of mining operations
• 6 node types: Mines, Trucks, Plants, Operators, Materials, Events
• 39 directed relationships capturing operational dependencies
• WebGL-accelerated rendering for 100+ node networks

⚡ Two-Tier Fault Simulation

• Simulate equipment failures and instantly see operational impact
• Direct impacts (Tier 1): Immediate operational dependency nodes in red
• Indirect impacts (Tier 2): Secondary effects through one intermediate connection in yellow
• No false positives—typed, directed graph traversal prevents hub contamination

📊 Operational Dashboards

• Real-time incident log with criticality sorting
• Node type counts and operational metrics
• Equipment status and capacity tracking
• Operational flow visualization (mines → materials → plants → products)

🔍 Smart Filtering

• Filter by equipment type (Mines, Trucks, Plants, Operators)
• Highlight node neighborhoods on click
• Color-coded visual hierarchy by impact severity

---

Quick Start

Prerequisites

• Python 3.8+
• Neo4j (local, self-hosted, or Aura cloud)
• Git

Local Development (2 minutes)

# Clone repository
git clone https://github.com/yourusername/stonelink.git
cd stonelink

# Create virtual environment
python -m venv venv
source venv/bin/activate          # macOS/Linux
# or
venv\Scripts\activate              # Windows

# Install dependencies
pip install -r requirements.txt

# Set up environment
cp .env.example .env
# Edit .env with your Neo4j credentials:
# NEO4J_URI=neo4j://localhost:7687
# NEO4J_USER=neo4j
# NEO4J_PASSWORD=your_password

# Import sample data (creates 31 nodes, 39 relationships)
python scripts/import_data.py

# Start Flask development server
python app.py

Open http://localhost:5000 in your browser. The graph loads automatically.

Production Deployment (Render + Neo4j Aura)

See DEPLOYMENT.md for step-by-step guide:

1. Create Render Web Service (2 min)
2. Create Neo4j Aura instance (2 min)
3. Set environment variables (2 min)
4. Push to GitHub (auto-deploy)

Result: Live app at https://stonelink-api-xxxxx.onrender.com

---

Project Structure

stonelink/
├── app.py                          # Flask backend (6 REST endpoints)
├── requirements.txt                # Python dependencies
├── Procfile                        # Render deployment config
├── runtime.txt                     # Python version for Render
├── .env.example                    # Environment template
├── .gitignore                      # Git ignore rules
│
├── static/
│   ├── index.html                  # Single-page app
│   ├── js/
│   │   └── app.js                  # Cytoscape visualization & fault simulation
│   └── css/
│       └── style.css               # Graph styling & impact colors
│
├── scripts/
│   ├── import_data.py              # Neo4j data import script
│   └── data/
│       ├── minas.csv               # Mining sites
│       ├── camiones.csv            # Trucks
│       ├── plantas.csv             # Processing plants
│       ├── operadores.csv          # Operators/drivers
│       ├── materiales.csv          # Materials
│       └── eventos.csv             # Incident logs
│
├── docs/
│   ├── ARCHITECTURE.md             # System design & topology
│   ├── API.md                      # REST endpoint reference
│   ├── DEPLOYMENT.md               # Production setup guide
│   └── README.md                   # This file
│
└── .claude/                        # Development metadata (ignored by git)

---

API Summary

Core Endpoints

Endpoint	Method	Purpose	Time
/api/graph	GET	Load full network graph	50-100ms
/api/simular_falla	POST	Simulate fault & get direct + indirect impacts	100-200ms
/api/eventos	GET	All incidents sorted by criticality	30-50ms
/api/metricas	GET	Node counts & operational summary	50-80ms
/api/flujo	GET	Operational flow (mines → plants)	50-100ms

Example: Fault Simulation

curl -X POST http://localhost:5000/api/simular_falla \
  -H 'Content-Type: application/json' \
  -d '{"equipo": "Cantera Central"}'

Response:

{
  "target": "Cantera Central",
  "target_label": "Mina",
  "target_id": "4",
  "direct_ids": ["8", "13", "17", "27"],
  "indirect_ids": ["5"],
  "direct_nodes": [
    {"id": 8, "label": "Camion", "nombre": "Volvo A40"},
    {"id": 13, "label": "Operador", "nombre": "Ana Rodriguez"},
    {"id": 17, "label": "Operador", "nombre": "Sofia Ruiz"},
    {"id": 27, "label": "Material", "nombre": "Grava gruesa"}
  ],
  "indirect_nodes": [
    {"id": 5, "label": "Planta", "nombre": "Planta B"}
  ]
}

Full endpoint reference: API.md

---

Two-Tier Impact Analysis

The fault simulation uses a directed, typed, depth-limited graph traversal to prevent false positives:

How It Works

When a node fails (e.g., Cantera Central mine):

Tier 1 (Direct Impact) — 1 hop with explicit relationship types:

Cantera Central (Mina)
├─ ← OPERA_EN → Volvo A40 (Camion)        [Trucks at this mine]
├─ ← TRABAJA_EN → Ana Rodriguez (Operador) [Workers there]
├─ ← TRABAJA_EN → Sofia Ruiz (Operador)   [Workers there]
└─ → GENERA → Grava gruesa (Material)     [What it produces]

Tier 2 (Indirect Impact) — 1 hop from each Tier-1 node:

Volvo A40 (Camion)
└─ → TRANSPORTA → Planta B (Planta)       [Delivery destination]

[Terminal: Operador and Material don't propagate further]

This is the beginning of the README. Read the rest at the original. Read the full README ↗