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

docs/modules/scanner/byos-ingestion.md

@@ -0,0 +1,33 @@
+# BYOS SBOM ingestion
+
+## Overview
+- Accepts external SBOMs and runs them through validation, normalization, and analysis triggers.
+- Stores the SBOM artifact in the scanner object store and records provenance metadata.
+- Emits a deterministic analysis job id tied to the upload metadata.
+
+## API
+- `POST /api/v1/sbom/upload`
+- `GET /api/v1/sbom/uploads/{sbomId}`
+
+Example request:
+```json
+{
+  "artifactRef": "example.com/app:1.0",
+  "sbomBase64": "<base64>",
+  "format": "cyclonedx",
+  "source": { "tool": "syft", "version": "1.0.0" }
+}
+```
+
+## Supported formats
+- CycloneDX JSON 1.4-1.6 (`bomFormat`, `specVersion`)
+- SPDX JSON 2.3 (`spdxVersion`)
+- SPDX JSON 3.0 (structural checks only; schema validation pending)
+
+## CLI
+`stella sbom upload --file sbom.json --artifact example.com/app:1.0`
+
+## Troubleshooting
+- Missing format: ensure `bomFormat` (CycloneDX) or `spdxVersion` (SPDX).
+- Unsupported versions: CycloneDX must be 1.4-1.6; SPDX must be 2.3 or 3.0.
+- Empty component lists are accepted but reduce quality scores.