#  15 - Pragmatic UI Guide --- **Stella Ops**

# Stella Ops Web UI

A fast, modular single‑page application for controlling scans, policies, offline updates and platform‑wide settings.  
Built for sub‑second feedback, dark‑mode by default, and **no external CDNs** – everything ships inside the anonymous internal registry.

---

## 0 Fast Facts

| Aspect            | Detail                                                                     |
| ----------------- | -------------------------------------------------------------------------- |
| Tech Stack        | **Angular {{ angular }}** + Vite dev server                                           |
| Styling           | **Tailwind CSS**                                                           |
| State             | Angular Signals + RxJS                                                     |
| API Client        | OpenAPI v3 generated services (Axios)                                      |
| Auth              | OAuth2 /OIDC (tokens from backend or external IdP)                         |
| i18n              | JSON bundles – **`/locales/{lang}.json`** (English, Russian shipped)       |
| Offline Updates 📌 | UI supports “OUK” tarball upload to refresh NVD / Trivy DB when air‑gapped |
| Build Artifacts   | (`ui/dist/`) pushed to `registry.git.stella-ops.org/ui:${SHA}`              |

---

## 1 Navigation Map

```
Dashboard
└─ Scans
   ├─ Active
   ├─ History
   └─ Reports
└─ Policies 📌
   ├─ Editor (YAML / Rego) 📌
   ├─ Import / Export 📌
   └─ History
└─ Settings
   ├─ SBOM Format 📌
   ├─ Registry 📌
   ├─ Offline Updates (OUK) 📌
   ├─ Themes (Light / Dark / System) 📌
   └─ Advanced
└─ Plugins 🛠
└─ Help / About
```

*The **Offline Updates (OUK)** node under **Settings** is new.*

---

## 2 Technology Overview

### 2.1 Build & Deployment

1. `npm i && npm build` → generates `dist/` (~2.1 MB gzip).  
2. A CI job tags and pushes the artifact as `ui:${GIT_SHA}` to the internal registry.  
3. Backend serves static assets from `/srv/ui` (mounted from the image layer).

_No external fonts or JS – true offline guarantee._

### 2.2 Runtime Boot

1. **AppConfigService** pulls `/api/v1/config/ui` (contains feature flags, default theme, enabled plugins).  
2. Locale JSON fetched (`/locales/{lang}.json`, falls back to `en`).  
3. Root router mounts lazy‑loaded **feature modules** in the order supplied by backend – this is how future route plugins inject pages without forking the UI.

---

## 3 Feature Walk‑Throughs

### 3.1 Dashboard – Real‑Time Status

* **Δ‑SBOM heat‑map** 📌 shows how many scans used delta mode vs. full unpack.  
* “Feed Age” tile turns **orange** if NVD feed is older than 24 h; reverts after an **OUK** upload 📌.  
* Live WebSocket updates for scans in progress (SignalR channel).
* **Quota Tile** – shows **Scans Today / {{ quota_token }}**; turns yellow at **≤ 10% remaining** (≈ 90% used),
  red at {{ quota_token }} .  
* **Token Expiry Tile** – shows days left on *client.jwt* (offline only);
  turns orange at < 7 days.

### 3.2 Scans Module

| View        | What you can do                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------- |
| **Active**  | Watch progress bar (ETA ≤ 5 s) – newly added **Format** and **Δ** badges appear beside each item. |
| **History** | Filter by repo, tag, policy result (pass/block/soft‑fail).                                        |
| **Reports** | Click row → HTML or PDF report rendered by backend (`/report/{digest}/html`).                     |

### 3.3 📌 Policies Module (new)

*Embedded **Monaco** editor with YAML + Rego syntax highlighting.*

| Tab                 | Capability                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------ |
| **Editor**          | Write or paste `scan-policy.yaml` or inline Rego snippet. Schema validation shown inline.        |
| **Import / Export** | Buttons map to `/policy/import` and `/policy/export`. Accepts `.yaml`, `.rego`, `.zip` (bundle). |
| **History**         | Immutable audit log; diff viewer highlights rule changes.                                        |

#### 3.3.1 YAML → Rego Bridge

If you paste YAML but enable **Strict Mode** (toggle), backend converts to Rego under the hood, stores both representations, and shows a side‑by‑side diff.

### 3.4 📌 Settings Enhancements

| Setting                     | Details                                                                                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SBOM Format**             | Dropdown – *Trivy JSON*, *SPDX JSON*, *CycloneDX JSON*.                                                                                                                    |
| **Registry**                | Displays pull URL (`registry.git.stella-ops.ru`) and Cosign key fingerprint.                                                                                               |
| **Offline Updates (OUK)** 📌 | Upload **`ouk*.tar.gz`** produced by the Offline Update Kit CLI. Backend unpacks, verifies SHA‑256 checksum & Cosign signature, then reloads Redis caches without restart. |
| **Theme**                   | Light, Dark, or Auto (system).                                                                                                                                             |

#### 3.4.1 OUK Upload Screen 📌

*Page path:* **Settings → Offline Updates (OUK)**  
*Components:*

1. **Drop Zone** – drag or select `.tar.gz` (max 1 GB).  
2. **Progress Bar** – streaming upload with chunked HTTP.  
3. **Verification Step** – backend returns status:  
   * *Signature valid* ✔️  
   * *Digest mismatch* ❌  
4. **Feed Preview** – table shows *NVD date*, *OUI source build tag*, *CVE count delta*.  
5. **Activate** – button issues `/feeds/activate/{id}`; on success the Dashboard “Feed Age” tile refreshes to green.  
6. **History List** – previous OUK uploads with user, date, version; supports rollback.

*All upload actions are recorded in the Policies → History audit log as type `ouk_update`.*

### 3.5 Plugins Panel 🛠 (ships after UI modularisation)

Lists discovered UI plugins; each can inject routes/panels. Toggle on/off without reload.

### 3.6 Settings → **Quota & Tokens** (new)

* View current **Client‑JWT claims** (tier, maxScansPerDay, expiry).  
* **Generate Offline Token** – admin‑only button → POST `/token/offline` (UI wraps the API).  
* Upload new token file for manual refresh.

---

## 4 i18n & l10n

* JSON files under `/locales`.  
* Russian (`ru`) ships first‑class, translated security terms align with **GOST R ISO/IEC 27002‑2020**.  
* “Offline Update Kit” surfaces as **“Оффлайн‑обновление базы уязвимостей”** in Russian locale.  
* Community can add locales by uploading a new JSON via Plugins Panel once 🛠 ships.

---

## 5 Accessibility

* WCAG 2.1 AA conformance targeted.  
* All color pairs pass contrast (checked by `vite-plugin-wcag`).  
* Keyboard navigation fully supported; focus outlines visible in both themes.

---

## 6 Theming 📌

| Layer           | How to change                                                |
| --------------- | ------------------------------------------------------------ |
| Tailwind        | Palette variables under `tailwind.config.js > theme.colors`. |
| Runtime toggle  | Stored in `localStorage.theme`, synced across tabs.          |
| Plugin override | Future route plugins may expose additional palettes 🛠.       |

---

## 7 Extensibility Hooks

| Area          | Contract                                 | Example                                        |
| ------------- | ---------------------------------------- | ---------------------------------------------- |
| New route     | `window.stella.registerRoute()`          | “Secrets” scanner plugin adds `/secrets` page. |
| External link | `window.stella.addMenuLink(label, href)` | “Docs” link opens corporate Confluence.        |
| Theme         | `window.stella.registerTheme()`          | High‑contrast palette for accessibility.       |

---

## 8 Road‑Map Tags

| Feature                   | Status |
| ------------------------- | ------ |
| Policy Editor (YAML)      | ✅      |
| Inline Rego validation    | 🛠      |
| OUK Upload UI             | ✅      |
| Plugin Marketplace UI     | 🚧      |
| SLSA Verification banner  | 🛠      |
| Rekor Transparency viewer | 🚧      |

---

## 9 Non‑Commercial Usage Rules 📌

*(Extracted & harmonised from the Russian UI help page so that English docs remain licence‑complete.)*

1. **Free for internal security assessments.**  
2. Commercial resale or SaaS re‑hosting **prohibited without prior written consent** under AGPL §13.  
3. If you distribute a fork **with UI modifications**, you **must**:  
   * Make the complete source code (including UI assets) publicly available.  
   * Retain original project attribution in footer.  
4. All dependencies listed in `ui/package.json` remain under their respective OSS licences (MIT, Apache 2.0, ISC).  
5. Use in government‑classified environments must comply with**applicable local regulations** governing cryptography and software distribution.

---

## 10 Troubleshooting Tips

| Symptom                             | Cause                               | Remedy                                                            |
| ----------------------------------- | ----------------------------------- | ----------------------------------------------------------------- |
| **White page** after login          | `ui/dist/` hash mismatch            | Clear browser cache; backend auto‑busts on version change.        |
| Policy editor shows “Unknown field” | YAML schema drift                   | Sync your policy file to latest sample in *Settings → Templates*. |
| **OUK upload fails** at 99 %        | Tarball built with outdated OUK CLI | Upgrade CLI (`ouk --version`) and rebuild package.                |
| Icons look broken in Safari         | *SVG `mask` unsupported*            | Use Safari 17+ or switch to PNG icon set in Settings > Advanced.  |

---

## 11 Contributing

* Run `npm dev` and open `http://localhost:5173`.  
* Ensure `ng lint` and `ng test` pass before PR.  
* Sign the **DCO** in your commit footer (`Signed-off-by`).  

---

## 12 Change Log

| Version | Date       | Highlights                                                                                                                       |
| ------- | ---------- |
| v2.4    | 2025‑07‑15 | **Added full OUK Offline Update upload flow** – navigation node, Settings panel, dashboard linkage, audit hooks.                 |
| v2.3    | 2025‑07‑14 | Added Policies module, SBOM Format & Registry settings, theming toggle, Δ‑SBOM indicators, extracted non‑commercial usage rules. |
| v2.2    | 2025‑07‑12 | Added user tips/workflows, CI notes, DevSecOps section, troubleshooting, screenshots placeholders.                               |
| v2.1    | 2025‑07‑12 | Removed PWA/Service‑worker; added oidc‑client‑ts; simplified roadmap                                                             |
| v2.0    | 2025‑07‑12 | Accessibility, Storybook, perf budgets, security rules                                                                           |
| v1.1    | 2025‑07‑11 | Original OSS‑only guide                                                                                                          |

(End of Pragmatic UI Guide v2.2)
