Initial commit (history squashed)

docs/40_ARCHITECTURE_OVERVIEW.md

@@ -0,0 +1,133 @@
+# Stella Ops — High‑Level Architecture
+
+<!--
+  Use constants injected at build:
+    {{ dotnet }}   = "10 LTS"
+    {{ angular }}  = "20"
+-->
+
+This document offers a birds‑eye view of how the major components interact,
+why the system leans *monolith‑plus‑plug‑ins*, and where extension points live.
+
+> For a *timeline* of when features arrive, see the public  
+> [road‑map](/roadmap/) — no version details are repeated here.
+
+---
+
+## 0 · Guiding principles
+
+| Principle | Rationale |
+|-----------|-----------|
+| **SBOM‑first** | Scan existing CycloneDX/SPDX if present; fall back to layer unpack. |
+| **Δ‑processing** | Re‑analyse only changed layers; reduces P95 warm path to \< 5 s. |
+| **All‑managed code** | Entire stack is 100 % managed (.NET / TypeScript); no `unsafe` blocks or native extensions — eases review and reproducible builds. |
+| **Restart‑time plug‑ins** | Avoids the attack surface of runtime DLL injection; still allows custom scanners & exporters. |
+| **Sovereign‑by‑design** | No mandatory outbound traffic; Offline Kit distributes feeds. |
+
+---
+
+## 1 · Module graph
+
+```mermaid
+graph TD
+    A(API Gateway)
+    B1(Scanner Core<br/>.NET latest LTS)
+    B2(Feedser service\n(vuln ingest/merge/export))
+    B3(Policy Engine OPA)
+    C1(Redis 7)
+    C2(MongoDB 7)
+    D(UI SPA<br/>Angular latest version)
+    A -->|gRPC| B1
+    B1 -->|async| B2
+    B1 -->|OPA| B3
+    B1 --> C1
+    B1 --> C2
+    A  -->|REST/WS| D
+````
+
+---
+
+## 2 · Key components
+
+| Component                    | Language / tech       | Responsibility                                       |
+| ---------------------------- | --------------------- | ---------------------------------------------------- |
+| **API Gateway**              | ASP.NET Minimal API   | Auth (JWT), quotas, request routing                  |
+| **Scanner Core**             | C# 12, Polly          | Layer diffing, SBOM generation, vuln correlation     |
+| **Feedser (vulnerability ingest/merge/export service)** | C# source-gen workers | Consolidate NVD + regional CVE feeds into the canonical MongoDB store and drive JSON / Trivy DB exports |
+| **Policy Engine**            | OPA (Rego)            | admission decisions, custom org rules                |
+| **Redis 7**                  | Key‑DB compatible     | LRU cache, quota counters                            |
+| **MongoDB 7**                | WiredTiger            | SBOM & findings storage                              |
+| **Angular {{ angular }} UI** | RxJS, Tailwind        | Dashboard, reports, admin UX                         |
+
+---
+
+## 3 · Plug‑in system
+
+* Discovered once at start‑up from `/opt/stella/plugins/**`.
+* Runs under Linux user `stella‑plugin` (UID 1001).
+* Extension points:
+
+  * `ISbomMutator`
+  * `IVulnerabilityProvider`
+  * `IResultSink`
+  * Policy files (`*.rego`)
+* Each DLL is SHA‑256 hashed; digest embedded in the run report for provenance.
+
+Hot‑plugging is deferred until after v 1.0 for security review.
+
+---
+
+## 4 · Data & control flow
+
+1. **Client** calls `/api/scan` with image reference.
+2. **Gateway** enforces quota, forwards to **Scanner Core** via gRPC.
+3. **Core**:
+
+   * Queries Redis for cached SBOM.
+   * If miss → pulls layers, generates SBOM.
+   * Executes plug‑ins (mutators, additional scanners).
+4. **Policy Engine** evaluates `scanResult` document.
+5. **Findings** stored in MongoDB; WebSocket event notifies UI.
+6. **ResultSink plug‑ins** export to Slack, Splunk, JSON file, etc.
+
+---
+
+## 5 · Security hardening
+
+| Surface           | Mitigation                                                   |
+| ----------------- | ------------------------------------------------------------ |
+| Container runtime | Distroless base, non‑root UID, seccomp + AppArmor            |
+| Plug‑in sandbox   | Separate UID, SELinux profile, cgroup 1 CPU / 256 MiB        |
+| Supply chain      | Cosign signatures, in‑toto SLSA Level 3 (target)             |
+| Secrets           | `Docker secrets` or K8s `Secret` mounts; never hard‑coded    |
+| Quota abuse       | Redis rate‑limit gates (see `30_QUOTA_ENFORCEMENT_FLOW1.md`) |
+
+---
+
+## 6 · Build & release pipeline (TL;DR)
+
+* **Git commits** trigger CI → unit / integration / E2E tests.
+* Successful merge to `main`:
+
+  * Build `.NET {{ dotnet }}` trimmed self‑contained binary.
+  * `docker build --sbom=spdx-json`.
+  * Sign image and tarball with Cosign.
+  * Attach SBOM + provenance; push to registry and download portal.
+
+---
+
+## 7 · Future extraction path
+
+Although the default deployment is a single container, each sub‑service can be
+extracted:
+
+* Feedser → standalone cron pod.
+* Policy Engine → side‑car (OPA) with gRPC contract.
+* ResultSink → queue worker (RabbitMQ or Azure Service Bus).
+
+Interfaces are stable **as of v0.2 β**; extraction requires a recompilation
+only, not a fork of the core.
+
+---
+
+*Last updated {{ "now" | date: "%Y‑%m‑%d" }} – constants auto‑injected.*