Refactor code structure for improved readability and maintainability; optimize performance in key functions.

docs/modules/sbomservice/lineage-ledger.md

@@ -0,0 +1,30 @@
+# SBOM lineage ledger
+
+## Overview
+- Tracks immutable SBOM versions per artifact reference.
+- Exposes history, temporal queries, and deterministic diffs.
+- Emits lineage edges to support graph joins and audit trails.
+
+## Endpoints
+- `GET /sbom/ledger/history?artifact=<ref>&limit=50&cursor=0`
+- `GET /sbom/ledger/point?artifact=<ref>&at=<iso8601>`
+- `GET /sbom/ledger/range?artifact=<ref>&start=<iso8601>&end=<iso8601>`
+- `GET /sbom/ledger/diff?before=<versionId>&after=<versionId>`
+- `GET /sbom/ledger/lineage?artifact=<ref>`
+
+## Lineage relationships
+- `parent`: explicit parent version link (supplied at ingest).
+- `build`: versions emitted from the same CI build ID (from upload provenance).
+
+## Example lineage response
+```json
+{
+  "artifactRef": "example.com/app:1.2.3",
+  "nodes": [{ "versionId": "v1", "sequenceNumber": 1, "digest": "sha256:..." }],
+  "edges": [{ "fromVersionId": "v1", "toVersionId": "v2", "relationship": "build" }]
+}
+```
+
+## Notes
+- Ledger storage is in-memory until PostgreSQL-backed persistence is wired.
+- Ordering is deterministic by sequence number, then timestamp.