adr for conceptual view

docs/adrs/00002-analysis-graph.md

@@ -0,0 +1,176 @@
+# 00002. Analysis graph API in Trustify
+
+Date: 2025-01-23
+
+## Status
+
+DRAFT
+
+## Context
+
+This ADR is an addenda to [previous ADR](00001-graph-analytics.md) as an attempt to clarify the differences between the graph
+relationships we capture and the view we want to create from the forest of graphs.
+
+Ingesting an sbom captures a set of trustify relationships, which are instantiated
+in the forest of graphs as;
+
+![Graph relations capture](00002-graph-relations-capture.svg)
+
+Trustify relationships attempt to put an abstraction over relationships 
+defined by any format of sbom (eg. cyclonedx, spdx). 
+
+Such a graph preserves provenance of sbom relationship though end users are unlikely 
+to directly navigate these graphs, which is a logical model of relationships... 
+we should be careful not to try and overload that model to also serve as the conceptual
+model. 
+
+The `api/v2/analysis` endpoints are responsible for building up the conceptual view. Where we want to query, filter and
+traverse on the following.
+
+![Conceptual model](00002-conceptual-model.svg)
+
+It is a feature that this conceptual model spans beyond traversal of just transitive software dependencies.  
+
+For example, searching for any node in any of the graphs, should let us traverse ancestors and descendents ... a 
+few illustrative examples:
+
+**Search for 'PackageA'**
+* component ancestors would be `[UpstreamComponent]`
+* component descendents would be the tree underneath 'PackageA' `[PackageOther,PackageD,PackageB]`
+
+**Search for 'image.arch1'**
+* component ancestors would be `[ImageIndex1]`
+* component descendents would be `[]`
+
+_Note: every node in the graph already knows its relationship to original SBOM so no need
+to enumerate DESCRIBES relationship ... though in the future we may see other artifacts (then sbom) 
+DESCRIBES._
+
+We should make it easy to visualise this conceptual model direct from the endpoints (ex. Accept: image/svg 
+would pull down an svg representation).
+
+## Decision
+
+* Implement `api/v2/analysis/component`
+
+payload returns immediate relations
+```json
+{
+  "sbom_id": "",
+  "node_id": "",
+  "purl": [
+    ""
+  ],
+  "cpe": [],
+  "name": "",
+  "version": "",
+  "published": "2024-12-19 18:04:12+00",
+  "document_id": "urn:uuid:537c8dc3-6f66-3cac-b504-cc5fb0a09ece",
+  "product_name": "",
+  "product_version": "",
+  "relation": [
+    {
+      "sbom_id": "",
+      "node_id": "",
+      "relationship": "Variant",
+      "purl": [
+        ""
+      ],
+      "cpe": [],
+      "name": "",
+      "version": ""
+    }
+  ]
+}
+```
+
+
+* Implement `api/v2/analysis/ancestor`
+  payload returns ancestor relations
+```json
+{
+  "sbom_id": "",
+  "node_id": "",
+  "purl": [
+    ""
+  ],
+  "cpe": [],
+  "name": "",
+  "version": "",
+  "published": "2024-12-19 18:04:12+00",
+  "document_id": "urn:uuid:537c8dc3-6f66-3cac-b504-cc5fb0a09ece",
+  "product_name": "",
+  "product_version": "",
+  "ancestor": [
+    {
+      "sbom_id": "",
+      "node_id": "",
+      "relationship": "ANCESTOR_OF",
+      "purl": [
+        ""
+      ],
+      "cpe": [],
+      "name": "",
+      "version": ""
+    }
+  ]
+}
+```
+
+* Implement `api/v2/analysis/descendent`
+returns descendent relations
+```json
+{
+  "sbom_id": "",
+  "node_id": "",
+  "purl": [
+    ""
+  ],
+  "cpe": [],
+  "name": "",
+  "version": "",
+  "published": "2024-12-19 18:04:12+00",
+  "document_id": "urn:uuid:537c8dc3-6f66-3cac-b504-cc5fb0a09ece",
+  "product_name": "",
+  "product_version": "",
+  "descendent": [
+    {
+      "sbom_id": "",
+      "node_id": "",
+      "relationship": "Variant",
+      "purl": [
+        ""
+      ],
+      "cpe": [],
+      "name": "",
+      "version": ""
+    }
+  ]
+}
+```
+
+* Implement `api/v2/analysis/relationship`
+  raw endpoint for querying relations
+```json
+TBA
+```
+
+* Document analysis graph API
+
+
+## Alternative approaches
+
+**Directly use graphs:** It is likely that we will provide raw interface to the graphs (aka `api/v2/analysis/relationship`) though
+we do not want to move responsibility of building up the 'view' to a client so still need
+to provide endpoints for that.
+
+**Build a new graph representing the conceptual model:** As graphs do not mutate, its not so far fetched to
+consider additionally generating a conceptual graph. It might be something we consider as an optimisation in 
+the future though for now thinking it would be good to avoid the cost (ram, memory). The conceptual graph model might be 
+considered a replacement for logical model though that would be flawed thinking as we always need the logical 
+model to tell us relationship provenance eg. the logical model is absolutely required.
+
+## Consequences
+
+* hopefully having a clear conceptual model will reduce cognitive load of having to mentally reparse graph relations
+* align conceptual model means we can also do neat stuff like make visual representations