Add filter, add READMES

backend_go/README.md

@@ -0,0 +1,98 @@
+# Backend (Go) – Graph + Selection API
+
+This service exposes a small HTTP API for:
+
+- Building and caching a “graph snapshot” from AnzoGraph via SPARQL (`/api/graph`)
+- Returning available “graph query” and “selection query” modes
+- Running selection queries for the currently selected node IDs
+- (Optionally) issuing raw SPARQL passthrough for debugging
+
+## Run
+
+Via Docker Compose (recommended):
+
+```bash
+docker compose up --build backend
+```
+
+The backend listens on `:8000` (configurable via `LISTEN_ADDR`).
+
+## Configuration (env)
+
+See `backend_go/config.go` for the full set.
+
+Important variables:
+
+- Snapshot limits:
+  - `DEFAULT_NODE_LIMIT`, `DEFAULT_EDGE_LIMIT`
+  - `MAX_NODE_LIMIT`, `MAX_EDGE_LIMIT`
+- SPARQL connectivity:
+  - `SPARQL_HOST` (default `http://anzograph:8080`) or `SPARQL_ENDPOINT`
+  - `SPARQL_USER`, `SPARQL_PASS`
+- Startup behavior:
+  - `SPARQL_LOAD_ON_START`, `SPARQL_CLEAR_ON_START`
+  - `SPARQL_DATA_FILE` (typically `file:///opt/shared-files/<file>.ttl`)
+- Other:
+  - `INCLUDE_BNODES` (include blank nodes in snapshots)
+  - `CORS_ORIGINS`
+
+## Endpoints
+
+- `GET /api/health`
+- `GET /api/stats`
+- `GET /api/graph?node_limit=&edge_limit=&graph_query_id=`
+- `GET /api/graph_queries`
+- `GET /api/selection_queries`
+- `POST /api/selection_query`
+  - Body: `{"query_id":"neighbors","selected_ids":[1,2,3],"node_limit":...,"edge_limit":...,"graph_query_id":"default"}`
+- `POST /api/sparql` (raw passthrough)
+- `POST /api/neighbors` (legacy alias of `query_id="neighbors"`)
+
+## Graph snapshots
+
+Snapshots are built by:
+
+1) Running a SPARQL edge query (controlled by `graph_query_id`)
+2) Converting SPARQL bindings into dense integer node IDs + edge list
+3) Computing a layout and fetching optional `rdfs:label`
+
+Snapshots are cached in-memory keyed by:
+
+- `node_limit`, `edge_limit`, `INCLUDE_BNODES`, `graph_query_id`
+
+## Query registries
+
+### Graph query modes (`graph_query_id`)
+
+Stored under `backend_go/graph_queries/` and listed by `GET /api/graph_queries`.
+
+Built-in modes:
+
+- `default` – `rdf:type` (to `owl:Class`) + `rdfs:subClassOf`
+- `hierarchy` – `rdfs:subClassOf` only
+- `types` – `rdf:type` (to `owl:Class`) only
+
+To add a new mode:
+
+1) Add a new file under `backend_go/graph_queries/` that returns a SPARQL query selecting `?s ?p ?o`.
+2) Register it in `backend_go/graph_queries/registry.go`.
+
+### Selection query modes (`query_id`)
+
+Stored under `backend_go/selection_queries/` and listed by `GET /api/selection_queries`.
+
+Built-in modes:
+
+- `neighbors` – type + subclass neighbors (both directions)
+- `superclasses` – `?sel rdfs:subClassOf ?nbr`
+- `subclasses` – `?nbr rdfs:subClassOf ?sel`
+
+To add a new mode:
+
+1) Add a new file under `backend_go/selection_queries/` that returns neighbor node IDs.
+2) Register it in `backend_go/selection_queries/registry.go`.
+
+## Performance notes
+
+- Memory usage is dominated by the cached snapshot (`[]Node`, `[]Edge`) and the temporary SPARQL JSON unmarshalling step.
+- Tune `DEFAULT_NODE_LIMIT`/`DEFAULT_EDGE_LIMIT` first if memory is too high.