# 7 · High‑Level Architecture — **Stella Ops**

---

## 0 Purpose & Scope  

Give contributors, DevOps engineers and auditors a **complete yet readable map** of the Core:

* Major runtime components and message paths.  
* Where plug‑ins, CLI helpers and runtime agents attach.  
* Technology choices that enable the sub‑5 second SBOM goal.  
* Typical operational scenarios (pipeline scan, mute, nightly re‑scan, etc.).  

Anything enterprise‑only (signed PDF, custom/regulated TLS, LDAP, enforcement) **must arrive as a plug‑in**; the Core never hard‑codes those concerns.
---
## 1 Component Overview  

| # | Component | Responsibility |
|---|-----------|---------------|
| 1 | **API Gateway** | REST endpoints (`/scan`, `/quota`, **`/token/offline`**); token auth; quota enforcement |
| 2 | **Scan Service** | SBOM parsing, Delta‑SBOM cache, vulnerability lookup |
| 3 | **Policy Engine** | YAML / (optional) Rego rule evaluation; verdict assembly |
| 4 | **Quota Service** | Per‑token counters; **333 scans/day**; waits & HTTP 429 |
| 5 | **Client‑JWT Issuer** | Issues 30‑day offline tokens; bundles them into OUK |
| 5 | **Registry** | Anonymous internal Docker registry for agents, SBOM uploads |
| 6 | **Web UI** | React/Blazor SPA; dashboards, policy editor, quota banner |
| 7 | **Data Stores** | **Redis** (cache, quota) & **MongoDB** (SBOMs, findings, audit) |
| 8 | **Plugin Host** | Hot‑load .NET DLLs; isolates community plug‑ins |
| 9 | **Agents** | `sbom‑builder`, `Stella CLI` scanner CLI, future `StellaOpsAttestor` |


```mermaid
flowchart TD
    subgraph "External Actors"
        DEV["Developer / DevSecOps / Manager"]
        CI["CI/CD Pipeline (e.g., Stella CLI)"]
        K8S["Kubernetes Cluster (e.g., Zastava Agent)"]
    end

    subgraph "Stella Ops Runtime"
        subgraph "Core Services"
            CORE["Stella Core<br>(REST + gRPC APIs, Orchestration)"]
            REDIS[("Redis<br>(Cache, Queues, Trivy DB Mirror)")]
            MONGO[("MongoDB<br>(Optional: Long-term Storage)")]
            POL["Mute Policies<br>(OPA & YAML Evaluator)"]
            REG["StellaOps Registry<br>(Docker Registry v2)"]
            ATT["StellaOps Attestor<br>(SLSA + Rekor)"]
        end

        subgraph "Agents & Builders"
            SB["SBOM Builder<br>(Go Binary: Extracts Layers, Generates SBOMs)"]
            SA["Stella CLI<br>(Pipeline Helper: Invokes Builder, Triggers Scans)"]
            ZA["Zastava Agent<br>(K8s Webhook: Enforces Policies, Inventories Containers)"]
        end

        subgraph "Scanners & UI"
            TRIVY["Trivy Scanner<br>(Plugin Container: Vulnerability Scanning)"]
            UI["Web UI<br>(Vue3 + Tailwind: Dashboards, Policy Editor)"]
            CLI["Stella CLI<br>(CLI Helper: Triggers Scans, Mutes)"]
        end
    end

    DEV -->|Browses Findings, Mutes CVEs| UI
    DEV -->|Triggers Scans| CLI
    CI -->|Generates SBOM, Calls /scan| SA
    K8S -->|Inventories Containers, Enforces Gates| ZA

    UI -- "REST" --> CORE
    CLI -- "REST/gRPC" --> CORE
    SA -->|Scan Requests| CORE
    SB -->|Uploads SBOMs| CORE
    ZA -->|Policy Gates| CORE

    CORE -- "Queues, Caches" --> REDIS
    CORE -- "Persists Data" --> MONGO
    CORE -->|Evaluates Policies| POL
    CORE -->|Attests Provenance| ATT
    CORE -->|Scans Vulnerabilities| TRIVY

    SB -- "Pulls Images" --> REG
    SA -- "Pulls Images" --> REG
    ZA -- "Pulls Images" --> REG

    style DEV fill:#f9f,stroke:#333
    style CI fill:#f9f,stroke:#333
    style K8S fill:#f9f,stroke:#333
    style CORE fill:#ddf,stroke:#333
    style REDIS fill:#fdd,stroke:#333
    style MONGO fill:#fdd,stroke:#333
    style POL fill:#dfd,stroke:#333
    style REG fill:#dfd,stroke:#333
    style ATT fill:#dfd,stroke:#333
    style SB fill:#fdf,stroke:#333
    style SA fill:#fdf,stroke:#333
    style ZA fill:#fdf,stroke:#333
    style TRIVY fill:#ffd,stroke:#333
    style UI fill:#ffd,stroke:#333
    style CLI fill:#ffd,stroke:#333
```

* **Developer / DevSecOps / Manager** – browses findings, mutes CVEs, triggers scans.  
* **Stella CLI** – generates SBOMs and calls `/scan` during CI.  
* **Zastava Agent** – inventories live containers; Core ships it in *passive* mode only (no kill).  

### 1.1 Client‑JWT Lifecycle (offline aware)

1. **Online instance** – user signs in → `/connect/token` issues JWT valid 12 h.  
2. **Offline instance** – JWT with `exp ≈ 30 days` ships in OUK; backend
   **re‑signs** and stores it during import.  
3. Tokens embed a `tier` claim (“Free”) and `maxScansPerDay: 333`.  
4. On expiry the UI surfaces a red toast **7 days** in advance.

---

## 2 · Component Responsibilities (runtime view)

| Component                  | Core Responsibility                                                                                        | Implementation Highlights                                 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Stella Core**            | Orchestrates scans, persists SBOM blobs, serves REST/gRPC APIs, fans out jobs to scanners & policy engine. | .NET {{ dotnet }}, CQRS, Redis Streams; pluggable runner interfaces. |
| **SBOM Builder**           | Extracts image layers, queries Core for *missing* layers, generates SBOMs (multi‑format), uploads blobs.   | Go binary; wraps Trivy & Syft libs.                       |
| **Stella CLI**          | Pipeline‑side helper; invokes Builder, triggers scan, streams progress back to CI/CD.                      | Static musl build.                                        |
| **Zastava Agent**          | K8s admission webhook enforcing policy verdicts before Pod creation.                                       | Rust for sub‑10 ms latencies.                             |
| **UI**                     | Angular 17 SPA for dashboards, settings, policy editor.                                                    | Tailwind CSS; Webpack module federation (future).         |
| **Redis**                  | Cache, queue, Trivy‑DB mirror, layer diffing.                                                              | Single instance or Sentinel.                              |
| **MongoDB** (opt.)         | Long‑term SBOM & policy audit storage (> 180 days).                                                        | Optional; enabled via flag.                               |
| **StellaOps.Registry**     | Anonymous read‑only Docker v2 registry with optional Cosign verification.                                  | `registry :2` behind nginx reverse proxy.                 |
| **StellaOps.MutePolicies** | YAML/Rego evaluator, policy version store, `/policy/*` API.                                                | Embeds OPA‑WASM; falls back to `opa exec`.                |
| **StellaOpsAttestor**      | Generate SLSA provenance & Rekor signatures; verify on demand.                                             | Side‑car container; DSSE + Rekor CLI.                     |

All cross‑component calls use dependency‑injected interfaces—no
intra‑component reach‑ins.

---

## 3 · Principal Backend Modules & Plug‑in Hooks  

| Namespace       | Responsibility                                     | Built‑in Tech / Default | Plug‑in Contract                                  |
| --------------- | -------------------------------------------------- | ----------------------- | ------------------------------------------------- |
| `configuration` | Parse env/JSON, health‑check endpoint              | .NET {{ dotnet }} Options | `IConfigValidator`                                |
| `identity`      | Embedded OAuth2/OIDC (OpenIddict 6)                | MIT OpenIddict          | `IIdentityProvider` for LDAP/SAML/JWT gateway     |
| `pluginloader`  | Discover DLLs, SemVer gate, optional Cosign verify | Reflection + Cosign     | `IPluginLifecycleHook` for telemetry              |
| `scanning`      | SBOM‑ & image‑flow orchestration; runner pool      | Trivy CLI (default)     | `IScannerRunner` – e.g., Grype, Copacetic, Clair  |
| `feedser` (vulnerability ingest/merge/export service) | Nightly NVD merge & feed enrichment                | Hangfire job            | drop-in `*.Schedule.dll` for OSV, GHSA, NVD 2.0, CNNVD, CNVD, ENISA, JVN and BDU feeds |
| `tls`           | TLS provider abstraction                           | OpenSSL                 | `ITlsProvider` for custom suites (incl. **SM2**, where law or security requires it) |
| `reporting`     | Render HTML/PDF reports                            | RazorLight              | `IReportRenderer`                                 |
| `ui`            | Angular SPA & i18n                                 | Angular {{ angular }}   | new locales via `/locales/{lang}.json`            |
| `scheduling`    | Cron + retries                                     | Hangfire                | any recurrent job via `*.Schedule.dll`            |

```mermaid
classDiagram
    class configuration
    class identity
    class pluginloader
    class scanning
    class feedser
    class tls
    class reporting
    class ui
    class scheduling

    class AllModules

    configuration ..> identity : Uses
    identity ..> pluginloader : Authenticates Plugins
    pluginloader ..> scanning : Loads Scanner Runners
    scanning ..> feedser : Triggers Feed Merges
    tls ..> AllModules : Provides TLS Abstraction
    reporting ..> ui : Renders Reports for UI
    scheduling ..> feedser : Schedules Nightly Jobs

    note for scanning "Pluggable: ISScannerRunner<br>e.g., Trivy, Grype"
    note for feedser "Pluggable: *.Schedule.dll<br>e.g., OSV, GHSA Feeds"
    note for identity "Pluggable: IIdentityProvider<br>e.g., LDAP, SAML"
    note for reporting "Pluggable: IReportRenderer<br>e.g., Custom PDF"
```

**When remaining = 0:**  
API returns `429 Too Many Requests`, `Retry‑After: <UTC‑midnight>` (sequence omitted for brevity).

---

## 4 · Data Flows  

### 4.1 SBOM‑First (≤ 5 s P95)  

Builder produces SBOM locally, so Core never touches the Docker
socket.
Trivy path hits ≤ 5 s on alpine:3.19 with warmed DB.
Image‑unpack fallback stays ≤ 10 s for 200 MB images.

```mermaid
sequenceDiagram
    participant CI as CI/CD Pipeline (Stella CLI)
    participant SB as SBOM Builder
    participant CORE as Stella Core
    participant REDIS as Redis Queue
    participant RUN as Scanner Runner (e.g., Trivy)
    participant POL as Policy Evaluator

    CI->>SB: Invoke SBOM Generation
    SB->>CORE: Check Missing Layers (/layers/missing)
    CORE->>REDIS: Query Layer Diff (SDIFF)
    REDIS-->>CORE: Missing Layers List
    CORE-->>SB: Return Missing Layers
    SB->>SB: Generate Delta SBOM
    SB->>CORE: Upload SBOM Blob (POST /scan(sbom))
    CORE->>REDIS: Enqueue Scan Job
    REDIS->>RUN: Fan Out to Runner
    RUN->>RUN: Perform Vulnerability Scan
    RUN-->>CORE: Return Scan Results
    CORE->>POL: Evaluate Mute Policies
    POL-->>CORE: Policy Verdict
    CORE-->>CI: JSON Verdict & Progress Stream
    Note over CORE,CI: Achieves ≤5s P95 with Warmed DB
```

### 4.2 Delta SBOM

Builder collects layer digests.
`POST /layers/missing` → Redis SDIFF → missing layer list (< 20 ms).
SBOM generated only for those layers and uploaded.

### 4.3 Feedser Harvest & Export

```mermaid
sequenceDiagram
    participant SCHED as Feedser Scheduler
    participant CONN as Source Connector Plug-in
    participant FEEDSER as Feedser Core
    participant MONGO as MongoDB (Canonical Advisories)
    participant EXPORT as Exporter (JSON / Trivy DB)
    participant ART as Artifact Store / Offline Kit

    SCHED->>CONN: Trigger window (init/resume)
    CONN->>CONN: Fetch source documents + metadata
    CONN->>FEEDSER: Submit raw document for parsing
    FEEDSER->>FEEDSER: Parse & normalize to DTO
    FEEDSER->>FEEDSER: Merge & deduplicate canonical advisory
    FEEDSER->>MONGO: Write advisory, provenance, merge_event
    FEEDSER->>EXPORT: Queue export delta request
    EXPORT->>MONGO: Read canonical snapshot/deltas
    EXPORT->>EXPORT: Build deterministic JSON & Trivy DB artifacts
    EXPORT->>ART: Publish artifacts / Offline Kit bundle
    ART-->>FEEDSER: Record export state + digests
```

### 4.4 Identity & Auth Flow

OpenIddict issues JWTs via client‑credentials or password grant.
An IIdentityProvider plug‑in can delegate to LDAP, SAML or external OIDC
without Core changes.
---
## 5 · Runtime Helpers  

| Helper    | Form                                  | Purpose                                                            | Extensible Bits                            |
|-----------|---------------------------------------|--------------------------------------------------------------------|-------------------------------------------|
| **Stella CLI** | Distroless CLI                       | Generates SBOM, calls `/scan`, honours threshold flag              | `--engine`, `--pdf-out` piped to plug‑ins |
| **Zastava** | Static Go binary / DaemonSet         | Watches Docker/CRI‑O events; uploads SBOMs; can enforce gate       | Policy plug‑in could alter thresholds     |

---

## 6 · Persistence & Cache Strategy  

| Store          | Primary Use                                   | Why chosen                     |
|----------------|-----------------------------------------------|--------------------------------|
| **MongoDB**    | Feedser canonical advisories, merge events, export state | Deterministic canonical store with flexible schema |
| **Redis 7**    | CLI quotas, short-lived job scheduling, layer diff cache | Sub-1 ms P99 latency for hot-path coordination |
| **Local tmpfs**| Trivy layer cache (`/var/cache/trivy`)        | Keeps disk I/O off hot path    |

```mermaid
flowchart LR
    subgraph "Persistence Layers"
        REDIS[(Redis: Quotas & Short-lived Queues<br>Sub-1ms P99)]
        MONGO[(MongoDB: Canonical Advisories<br>Merge Events & Export State)]
        TMPFS[(Local tmpfs: Trivy Layer Cache<br>Low I/O Overhead)]
    end

    CORE["Stella Core"] -- Queues & SBOM Cache --> REDIS
    CORE -- Long-term Storage --> MONGO
    TRIVY["Trivy Scanner"] -- Layer Unpack Cache --> TMPFS

    style REDIS fill:#fdd,stroke:#333
    style MONGO fill:#dfd,stroke:#333
    style TMPFS fill:#ffd,stroke:#333
```

---

## 7 · Typical Scenarios  

| #       | Flow                       | Steps                                                                                           |
|---------|----------------------------|-------------------------------------------------------------------------------------------------|
| **S‑1** | Pipeline Scan & Alert     | Stella CLI → SBOM → `/scan` → policy verdict → CI exit code & link to *Scan Detail*                |
| **S‑2** | Mute Noisy CVE            | Dev toggles **Mute** in UI → rule stored in Redis → next build passes                           |
| **S‑3** | Nightly Re‑scan           | `SbomNightly.Schedule` re‑queues SBOMs (mask‑filter) → dashboard highlights new Criticals       |
| **S‑4** | Feed Update Cycle         | `Feedser (vulnerability ingest/merge/export service)` refreshes feeds → UI *Feed Age* tile turns green |
| **S‑5** | Custom Report Generation  | Plug‑in registers `IReportRenderer` → `/report/custom/{digest}` → CI downloads artifact         |

```mermaid
sequenceDiagram
    participant DEV as Developer
    participant UI as Web UI
    participant CORE as Stella Core
    participant REDIS as Redis
    participant RUN as Scanner Runner

    DEV->>UI: Toggle Mute for CVE
    UI->>CORE: Update Mute Rule (POST /policy/mute)
    CORE->>REDIS: Store Mute Policy
    Note over CORE,REDIS: YAML/Rego Evaluator Updates

    alt Next Pipeline Build
        CI->>CORE: Trigger Scan (POST /scan)
        CORE->>RUN: Enqueue & Scan
        RUN-->>CORE: Raw Findings
        CORE->>REDIS: Apply Mute Policies
        REDIS-->>CORE: Filtered Verdict (Passes)
        CORE-->>CI: Success Exit Code
    end
```

```mermaid
sequenceDiagram
    participant CRON as SbomNightly.Schedule
    participant CORE as Stella Core
    participant REDIS as Redis Queue
    participant RUN as Scanner Runner
    participant UI as Dashboard

    CRON->>CORE: Re-queue SBOMs (Mask-Filter)
    CORE->>REDIS: Enqueue Filtered Jobs
    REDIS->>RUN: Fan Out to Runners
    RUN-->>CORE: New Scan Results
    CORE->>UI: Highlight New Criticals
    Note over CORE,UI: Focus on Changes Since Last Scan
```
---

## 8 · UI Fast Facts  

* **Stack** – Angular 17 + Vite dev server; Tailwind CSS.  
* **State** – Signals + RxJS for live scan progress.  
* **i18n / l10n** – JSON bundles served from `/locales/{lang}.json`.  
* **Module Structure** – Lazy‑loaded feature modules (`dashboard`, `scans`, `settings`); runtime route injection by UI plug‑ins (road‑map Q2‑2026).  

---

## 9 · Cross‑Cutting Concerns  

* **Security** – containers run non‑root, `CAP_DROP:ALL`, read‑only FS, hardened seccomp profiles.  
* **Observability** – Serilog JSON, OpenTelemetry OTLP exporter, Prometheus `/metrics`.  
* **Upgrade Policy** – `/api/v1` endpoints & CLI flags stable across a minor; breaking changes bump major.  

---

## 10 · Performance & Scalability  

| Scenario        | P95 target | Bottleneck      | Mitigation                                      |
|-----------------|-----------:|-----------------|-------------------------------------------------|
| SBOM‑first      | ≤ 5 s      | Redis queue     | More CPU, increase `ScannerPool.Workers`        |
| Image‑unpack    | ≤ 10 s     | Layer unpack    | Prefer SBOM path, warm Docker cache             |
| High concurrency| 40 rps     | Runner CPU      | Scale Core replicas + side‑car scanner services |

---

## 11 · Future Architectural Anchors  

* **ScanService micro‑split (gRPC)** – isolate heavy runners for large clusters.  
* **UI route plug‑ins** – dynamic Angular module loader (road‑map Q2‑2026).  
* **Redis Cluster** – transparently sharded cache once sustained > 100 rps.  

---

## 12 · Assumptions & Trade‑offs  

Requires Docker/CRI‑O runtime; .NET 9 available on hosts; Windows containers are out‑of‑scope this cycle.  
Embedded auth simplifies deployment but may need plug‑ins for enterprise IdPs.  
Speed is prioritised over exhaustive feature parity with heavyweight commercial scanners.

---

## 13 · References & Further Reading  

* **C4 Model** – <https://c4model.com>  
* **.NET Architecture Guides** – <https://learn.microsoft.com/dotnet/architecture>  
* **OSS Examples** – Kubernetes Architecture docs, Prometheus design papers, Backstage.  

*(End of High‑Level Architecture v2.2)*