# 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(Concelier 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     |
| **Concelier (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:

* Concelier → 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.*