visualizador_instanciados/README.md

Visualizador Instanciados

This repo is a Docker Compose stack for visualizing large RDF/OWL graphs stored in AnzoGraph. It includes:

• A Go backend that queries AnzoGraph via SPARQL and serves a cached graph snapshot + selection queries.
• A React/Vite frontend that renders nodes/edges with WebGL2 and supports “selection query” + “graph query” modes.
• A Python one-shot service to combine owl:imports into a single Turtle file.
• An AnzoGraph container (SPARQL endpoint).

Quick start (Docker Compose)

1. Put your TTL file(s) in ./data/ (this folder is volume-mounted into AnzoGraph as /opt/shared-files).
2. Optionally configure .env (see .env.example).
3. Start the stack:

docker compose up --build

Then open the frontend:

• http://localhost:5173

Stop everything:

docker compose down

Services

Defined in docker-compose.yml:

• anzograph (image cambridgesemantics/anzograph:latest)
  • Ports: 8080, 8443
  • Shared files: ./data → /opt/shared-files
• backend (./backend_go)
  • Port: 8000 (API under /api/*)
  • Talks to AnzoGraph at SPARQL_HOST / SPARQL_ENDPOINT
• frontend (./frontend)
  • Port: 5173
  • Proxies /api/* to VITE_BACKEND_URL
• owl_imports_combiner (./python_services/owl_imports_combiner)
  • One-shot: optionally produces a combined TTL by following owl:imports

Service READMEs:

• backend_go/README.md
• frontend/README.md
• python_services/owl_imports_combiner/README.md
• anzograph/README.md

Repo layout

• backend_go/ – Go API service (SPARQL → snapshot + selection queries)
• frontend/ – React/Vite WebGL renderer
• python_services/owl_imports_combiner/ – Python one-shot OWL imports combiner
• data/ – local shared volume for TTL inputs/outputs (gitignored)
• docker-compose.yml – service wiring
• flake.nix – optional Nix dev shell

Configuration

This repo expects a local .env file (not committed). Start from .env.example.

Common knobs:

• Backend snapshot size: DEFAULT_NODE_LIMIT, DEFAULT_EDGE_LIMIT, MAX_NODE_LIMIT, MAX_EDGE_LIMIT
• SPARQL connectivity: SPARQL_HOST or SPARQL_ENDPOINT, plus SPARQL_USER / SPARQL_PASS
• Load data on backend startup: SPARQL_LOAD_ON_START=true with SPARQL_DATA_FILE=file:///opt/shared-files/<file>.ttl
• Frontend → backend proxy: VITE_BACKEND_URL

API (backend)

Base URL: http://localhost:8000

• GET /api/health – liveness
• GET /api/stats – snapshot stats (uses default limits)
• GET /api/graph – graph snapshot
  • Query params: node_limit, edge_limit, graph_query_id
• GET /api/graph_queries – available graph snapshot modes (graph_query_id values)
• GET /api/selection_queries – available selection-highlight modes (query_id values)
• POST /api/selection_query – run a selection query for highlighted neighbors
  • Body: {"query_id":"neighbors","selected_ids":[...],"node_limit":...,"edge_limit":...,"graph_query_id":"default"}
• POST /api/sparql – raw SPARQL passthrough (debug/advanced)
• POST /api/neighbors – legacy alias (same behavior as query_id="neighbors")

Frontend UI

• Mouse:
  • Drag: pan
  • Scroll: zoom
  • Click: select nodes
• Top-right buttons: “selection query” mode (how neighbors/highlights are computed for the current selection)
• Bottom-right buttons: “graph query” mode (which SPARQL edge set is used to build the graph snapshot; switching reloads the graph)

Notes on performance/limits

• The backend caches snapshots in memory; tune DEFAULT_*_LIMIT if memory is too high.
• The frontend renders a sampled subset when zoomed out, and only draws edges when fewer than ~20k nodes are visible.

Nix dev shell (optional)

If you use Nix, flake.nix provides a minimal devShell:

nix develop