visualizador_instanciados/CURRENT_HIERARCHY_PIPELINE.md

# Current `subClassOf` / `BFO:entity` Pipeline

This document summarizes how the repository currently builds the hierarchy that ends up in the radial Sugiyama layout, with special attention to the fact that "start from `bfo:entity`" is **not** implemented in the initial `subClassOf` query.

`bfo:entity` here means:

- `http://purl.obolibrary.org/obo/BFO_0000001`

## TL;DR

- The current code does **not** query "all `rdfs:subClassOf` relationships rooted at `bfo:entity`" directly.
- It first queries the **entire** `rdfs:subClassOf` graph.
- It builds an in-memory graph from those triples.
- Only later, in the Rust hierarchy layout bridge, it filters that graph to the descendant closure of the configured root IRI.
- Because of that, the "rooted at `bfo:entity`" behavior is currently coupled to the layout pipeline instead of existing as a reusable graph-extraction stage.

## Where The Request Starts

The frontend loads the hierarchy through the normal graph endpoint:

1. `frontend/src/App.tsx`
2. `GET /api/graph?graph_query_id=hierarchy`
3. `backend_go/server.go` -> `handleGraph`
4. `backend_go/snapshot_service.go` -> `Get`
5. `backend_go/graph_snapshot.go` -> `fetchGraphSnapshot`

Important consequence:

- The hierarchy is treated as a graph snapshot mode, not as a dedicated "query descendants of this root" pipeline.

## The Actual SPARQL Query Used For `hierarchy`

The `hierarchy` graph query is defined in:

- `backend_go/graph_queries/hierarchy.go`

It effectively does:

```sparql
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?s ?p ?o
WHERE {
  VALUES ?p { rdfs:subClassOf }
  ?s ?p ?o .
  FILTER(!isLiteral(?o))
  # optionally also FILTER(!isBlank(?s) && !isBlank(?o))
}
ORDER BY ?s ?p ?o
LIMIT ...
OFFSET ...
```

Important facts:

- It queries **all** `rdfs:subClassOf` triples.
- There is **no root restriction** here.
- There is **no `bfo:entity` filter** here.
- Blank nodes are excluded unless `INCLUDE_BNODES=true`.
- Objects that are literals are excluded.

## How The In-Memory Graph Is Built

Graph construction is handled by:

- `backend_go/graph_export.go`

The accumulator logic works like this:

- Every returned `?s` and `?o` becomes a node if it has not been seen before.
- There is no separate node query.
- A class only enters the graph if it appears in at least one fetched edge.
- Isolated classes with no fetched `subClassOf` edge never appear.
- If `node_limit` is reached, new nodes stop being added, and edges that depend on them are skipped.

Edge direction at this stage is:

- `Source = subclass (?s)`
- `Target = superclass (?o)`

So the raw in-memory graph is stored as:

- `subclass -> superclass`

## Where `BFO:entity` Is Actually Applied

The root restriction happens only when the backend chooses the Rust hierarchy layout path.

Relevant files:

- `backend_go/config.go`
- `.env`
- `backend_go/graph_snapshot.go`
- `backend_go/hierarchy_layout_bridge.go`
- `radial_sugiyama/src/bridge.rs`

Current behavior:

- `.env` sets `HIERARCHY_LAYOUT_ENGINE=rust`.
- If `graph_query_id == "hierarchy"` and the engine is `rust`, the backend calls the Rust bridge.
- The root IRI comes from `HIERARCHY_LAYOUT_ROOT_IRI`.
- If that env var is not set, the checked-in default is `http://purl.obolibrary.org/obo/BFO_0000001`.

This means the current repository behavior is effectively:

- query all `subClassOf`
- then filter to descendants of `BFO:entity`
- then lay out the filtered graph

## What Go Sends To Rust

Before calling Rust, Go rewrites the edge orientation in:

- `backend_go/hierarchy_layout_bridge.go`

It converts each stored edge from:

- `subclass -> superclass`

into:

- `parentID = superclass`
- `childID = subclass`

So the Rust side receives:

- `superclass -> subclass`

Go also:

- de-duplicates repeated parent/child edges
- sends the configured `root_iri`
- sends all nodes that were present in the fetched hierarchy graph

## How Rust Filters To Descendants Of The Root

Filtering happens in:

- `radial_sugiyama/src/bridge.rs`

The bridge logic does this:

1. Build an internal graph from the request.
2. Find the node whose label/IRI matches `root_iri`.
3. Build adjacency lists in the `parent -> child` direction.
4. Run a BFS/queue traversal starting at the root.
5. Keep only the visited nodes.
6. Keep only edges whose endpoints are both visited.
7. Run radial Sugiyama layout on that filtered subgraph.

Important consequences:

- Nodes outside the descendant closure of the root are dropped.
- Disconnected components are dropped.
- Ancestors of the root are not kept unless they are also reachable as descendants, which normally they are not.
- If the root is missing, the pipeline errors.
- If the root has no descendants, the pipeline errors.

So the actual "select only those starting from `bfo:entity`" logic is:

- **graph traversal after fetching the full hierarchy**

not:

- **root-constrained SPARQL**

## What Comes Back From Rust

After Rust finishes:

- only the filtered nodes are returned
- only edges between retained nodes are returned
- routed edge segments are returned for drawing

That filtering is applied back onto the original Go snapshot response, so the final `/api/graph?graph_query_id=hierarchy` response only contains the root-descendant subgraph when the Rust path is active.

## Why This Feels Like A Separate Pipeline

The main reason it feels split is that the current behavior crosses multiple stages:

1. SPARQL query stage fetches the whole `subClassOf` graph.
2. Graph materialization stage builds a generic snapshot graph.
3. Layout bridge stage applies the root restriction.
4. Layout stage computes coordinates.

This means the "hierarchy rooted at `BFO:entity`" concept is currently embedded in layout preparation instead of existing as a first-class reusable data pipeline.

In practice, the root filtering is:

- not reusable by itself through a dedicated backend API
- not expressed in the initial SPARQL query
- not controlled per request
- tied to the hierarchy layout engine choice

## Selection Queries Are A Different Mechanism

The repository also has separate selection-query endpoints:

- `backend_go/selection_queries/subclasses.go`
- `backend_go/selection_queries/superclasses.go`
- `backend_go/selection_queries/neighbors.go`

Those are used after nodes are already present in a graph snapshot and the user selects node IDs.

They are **not** the mechanism that initially builds the `BFO:entity` hierarchy used by the radial layout.

Their role is more like:

- "given selected node IDs in the current snapshot, query related triples"

not:

- "materialize the hierarchy rooted at `BFO:entity`"

## Current End-To-End Behavior In One Sentence

The current system gets all `rdfs:subClassOf` triples first, constructs a general hierarchy graph, and only then filters it to the descendants of `http://purl.obolibrary.org/obo/BFO_0000001` inside the Rust radial Sugiyama bridge.

## Files To Read When Rewriting

If you want to rewrite this from zero, these are the main files that define the current behavior:

- `backend_go/server.go`
- `backend_go/snapshot_service.go`
- `backend_go/graph_snapshot.go`
- `backend_go/graph_queries/hierarchy.go`
- `backend_go/graph_export.go`
- `backend_go/hierarchy_layout_bridge.go`
- `backend_go/config.go`
- `.env`
- `radial_sugiyama/src/bridge.rs`
- `backend_go/selection_queries/subclasses.go`
- `backend_go/selection_queries/superclasses.go`

## Rewrite-Oriented Takeaway

If your goal is a cleaner standalone pipeline for:

- query `rdfs:subClassOf`
- start from `bfo:entity`
- materialize only the rooted descendant hierarchy

then the current codebase is doing the root restriction too late. Right now, that concern lives in the layout bridge rather than in the query/materialization layer.