# component_architecture_web.md - **Stella Ops Web** (2025Q4)

> Angular 21 frontend SPA for StellaOps console.

> **Scope.** Frontend architecture for **Web**: the Angular 21 single-page application providing the StellaOps console interface.

> **Note:** For the comprehensive Web UI architecture including all features, see [`../ui/architecture.md`](../ui/architecture.md). This file provides a condensed overview.

---

## 0) Mission & boundaries

**Mission.** Provide an **intuitive, responsive web interface** for StellaOps operators to manage scans, review findings, configure policies, and monitor system health.

**Boundaries.**

* Web is a **frontend-only** application. All data comes from backend APIs.
* Web **does not** store sensitive data locally beyond session tokens.
* Supports **offline-first** patterns for air-gapped console access.

---

## 1) Solution & project layout

```
src/Web/StellaOps.Web/
 ├─ src/
 │   ├─ app/
 │   │   ├─ core/                    # Core services, guards, interceptors
 │   │   │   ├─ services/
 │   │   │   ├─ guards/
 │   │   │   └─ interceptors/
 │   │   ├─ shared/                  # Shared components, pipes, directives
 │   │   │   ├─ components/
 │   │   │   ├─ pipes/
 │   │   │   └─ directives/
 │   │   ├─ features/                # Feature modules
 │   │   │   ├─ dashboard/
 │   │   │   ├─ scans/
 │   │   │   ├─ findings/
 │   │   │   ├─ policies/
 │   │   │   ├─ settings/
 │   │   │   └─ admin/
 │   │   └─ app.routes.ts
 │   ├─ assets/
 │   ├─ environments/
 │   └─ styles/
 ├─ angular.json
 ├─ package.json
 └─ tsconfig.json
```

---

## 2) Technology stack

* **Framework**: Angular 21 with standalone components
* **State management**: NgRx Signals
* **UI components**: Angular Material
* **HTTP**: Angular HttpClient with interceptors
* **Routing**: Angular Router with lazy loading
* **Build**: Angular CLI with esbuild

---

## 3) Key features

| Feature | Path | Description |
|---------|------|-------------|
| Dashboard | `/dashboard` | Overview metrics and alerts |
| Scans | `/scans` | Scan history and details |
| Findings | `/findings` | Vulnerability findings list |
| Compare | `/compare` | Diff view between scans |
| Policies | `/policies` | Policy configuration |
| Settings | `/settings` | User and system settings |

### 3.1 VEX Gate Inline Actions (Sprint 20260208_073)

Quiet-triage promote actions now support inline VEX gating with deterministic evidence tiers:

- `src/Web/StellaOps.Web/src/app/features/vex_gate/vex-gate-button.directive.ts`
  - Morphs action buttons into tier-aware gate states:
    - Tier 1 -> green (`allow`)
    - Tier 2 -> amber (`review`)
    - Tier 3 -> red (`block`)
  - Emits a `gateBlocked` event on tier-3 actions.
- `src/Web/StellaOps.Web/src/app/features/vex_gate/vex-evidence-sheet.component.ts`
  - Renders inline evidence details with tier/verdict metadata and optional DSSE verification hints.
- Integrated in quiet-triage lane promote actions:
  - `src/Web/StellaOps.Web/src/app/features/triage/components/quiet-lane/quiet-lane-container.component.ts`
  - `src/Web/StellaOps.Web/src/app/features/triage/components/quiet-lane/parked-item-card.component.ts`

The UI behavior remains offline-first and deterministic:
- Tier mapping is derived from local finding attributes only.
- No additional network dependency is required to render gate/evidence states.

### 3.2 Signals Runtime Dashboard (Sprint 20260208_072)

Signals runtime operations now include a dedicated dashboard route:

- Route: `ops/signals`
- Route registration:
  - `src/Web/StellaOps.Web/src/app/app.routes.ts`
  - `src/Web/StellaOps.Web/src/app/features/signals/signals.routes.ts`
- Feature implementation:
  - `src/Web/StellaOps.Web/src/app/features/signals/signals-runtime-dashboard.component.ts`
  - `src/Web/StellaOps.Web/src/app/features/signals/services/signals-runtime-dashboard.service.ts`
  - `src/Web/StellaOps.Web/src/app/features/signals/models/signals-runtime-dashboard.models.ts`

Dashboard behavior:

- Aggregates signal runtime metrics (`signals/sec`, error rate, average latency) using `SignalsClient` and falls back to gateway request summaries when available.
- Computes deterministic per-host probe health snapshots (eBPF/ETW/dyld/unknown) from signal payload telemetry.
- Presents provider/status distribution summaries and probe status tables without introducing network-only dependencies beyond existing local API clients.

Verification coverage:

- `src/Web/StellaOps.Web/src/tests/signals_runtime_dashboard/signals-runtime-dashboard.service.spec.ts`
- `src/Web/StellaOps.Web/src/tests/signals_runtime_dashboard/signals-runtime-dashboard.component.spec.ts`

### 3.3 Audit Trail Reason Capsule (Sprint 20260208_067)

Findings and triage views now expose a per-row "Why am I seeing this?" reason capsule:

- Audit reasons client contract:
  - `src/Web/StellaOps.Web/src/app/core/api/audit-reasons.client.ts`
  - Uses `/api/audit/reasons/:verdictId` with deterministic fallback records for offline/unavailable API conditions.
- Reusable capsule component:
  - `src/Web/StellaOps.Web/src/app/features/triage/components/reason-capsule/reason-capsule.component.ts`
  - Displays policy name, rule ID, graph revision ID, and inputs digest.
- UI integration points:
  - `src/Web/StellaOps.Web/src/app/features/findings/findings-list.component.ts`
  - `src/Web/StellaOps.Web/src/app/features/findings/findings-list.component.html`
  - `src/Web/StellaOps.Web/src/app/features/triage/components/triage-list/triage-list.component.ts`

Verification coverage:

- `src/Web/StellaOps.Web/src/tests/audit_reason_capsule/audit-reasons.client.spec.ts`
- `src/Web/StellaOps.Web/src/tests/audit_reason_capsule/reason-capsule.component.spec.ts`
- `src/Web/StellaOps.Web/src/tests/audit_reason_capsule/findings-list.reason-capsule.spec.ts`

### 3.4 Pack Registry Browser (Sprint 20260208_068)

TaskRunner pack operations now include a dedicated registry browser route:

- Route: `ops/packs`
- Route registration:
  - `src/Web/StellaOps.Web/src/app/app.routes.ts`
  - `src/Web/StellaOps.Web/src/app/features/pack-registry/pack-registry.routes.ts`
- Feature implementation:
  - `src/Web/StellaOps.Web/src/app/features/pack-registry/pack-registry-browser.component.ts`
  - `src/Web/StellaOps.Web/src/app/features/pack-registry/services/pack-registry-browser.service.ts`
  - `src/Web/StellaOps.Web/src/app/features/pack-registry/models/pack-registry-browser.models.ts`

Browser behavior:

- Lists available and installed packs using `PackRegistryClient`, with deterministic ordering and capability filters.
- Displays DSSE signature status per pack and per version history entry (`verified`, `present`, `unsigned`) and signer metadata when available.
- Executes install/upgrade actions only after compatibility evaluation; incompatible packs are blocked with explicit operator feedback.
- Supports version-history drill-down per pack without introducing additional external dependencies.

Verification coverage:

- `src/Web/StellaOps.Web/src/tests/pack_registry_browser/pack-registry-browser.service.spec.ts`
- `src/Web/StellaOps.Web/src/tests/pack_registry_browser/pack-registry-browser.component.spec.ts`

### 3.5 Pipeline Run-Centric View (Sprint 20260208_069)

Release Orchestrator now provides a unified pipeline run-centric surface that links release status, approvals, deployment progress, evidence state, and first-signal telemetry:

- Route registration:
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/dashboard/dashboard.routes.ts`
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/runs/runs.routes.ts`
- Feature implementation:
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/runs/models/pipeline-runs.models.ts`
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/runs/services/pipeline-runs.service.ts`
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/runs/pipeline-runs-list.component.ts`
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/runs/pipeline-run-detail.component.ts`
- Dashboard integration entry point:
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/dashboard/dashboard.component.html`
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/dashboard/dashboard.component.ts`
  - `src/Web/StellaOps.Web/src/app/features/release-jobengine/dashboard/dashboard.component.scss`

Run-centric behavior:

- Normalizes recent releases into deterministic `pipeline-<releaseId>` run IDs.
- Correlates approvals and active deployments to each run for one-table operator triage.
- Provides per-run stage progression (scan, gates, approval, evidence, deployment) with explicit status details.
- Integrates `FirstSignalCardComponent` on run detail pages for first-signal evidence visibility.

Verification coverage:

- `src/Web/StellaOps.Web/src/tests/pipeline_run_centric/pipeline-runs.service.spec.ts`
- `src/Web/StellaOps.Web/src/tests/pipeline_run_centric/pipeline-runs-list.component.spec.ts`

### 3.6 Reachability Center Coverage Summary (Sprint 20260208_070)

Reachability Center now includes explicit asset/sensor coverage summaries and missing-sensor indicators:

- Feature implementation:
  - `src/Web/StellaOps.Web/src/app/features/reachability/reachability-center.component.ts`
- Verification coverage:
  - `src/Web/StellaOps.Web/src/app/features/reachability/reachability-center.component.spec.ts`

Coverage behavior:

- Computes deterministic fleet asset coverage percent from fixture rows.
- Computes deterministic runtime sensor coverage percent from online vs expected sensors.
- Surfaces a missing-sensor indicator section listing impacted assets and supports one-click filtering to `missing`.
- Shows per-row sensor gap labels (`all sensors online`, `missing N sensors`) to make observation gaps explicit.

### 3.7 SBOM Graph Reachability Overlay with Time Slider (Sprint 20260208_071)

Graph explorer overlay behavior now supports deterministic lattice-state reachability halos with temporal snapshot exploration:

- Feature implementation:
  - `src/Web/StellaOps.Web/src/app/features/graph/graph-overlays.component.ts`
  - `src/Web/StellaOps.Web/src/app/features/graph/graph-canvas.component.ts`

Behavior details:

- Reachability legend in overlay controls maps lattice states `SR/SU/RO/RU/CR/CU/X` to explicit halo colors.
- Time slider now binds to deterministic snapshot checkpoints (`current`, `1d`, `7d`, `30d`) and renders timeline event text for each selection.
- Reachability mock data generation is deterministic per `(nodeId, snapshot)` so repeated runs produce stable lattice status, confidence, and observation timestamps.
- Canvas halo stroke colors are derived from lattice state (not generic status), and halo titles include lattice state plus observed timestamp for operator audit context.

Verification coverage:

- `src/Web/StellaOps.Web/src/tests/graph_reachability_overlay/graph-overlays.component.spec.ts`
- `src/Web/StellaOps.Web/src/tests/graph_reachability_overlay/graph-canvas.component.spec.ts`

---

## 4) Authentication

* **OIDC/OAuth2** via Authority module
* **Token refresh** handled by interceptor
* **Session timeout** with configurable duration

---

## 5) Configuration

```typescript
// environment.ts
export const environment = {
  production: false,
  apiUrl: 'http://localhost:5000/api/v1',
  authorityUrl: 'http://localhost:5001',
  clientId: 'stellaops-web'
};
```

---

## Related Documentation

* UI module: `../ui/architecture.md`
* Authority: `../authority/architecture.md`
* Auth smoke tests: `../ui/operations/auth-smoke.md`

## 6) Signed Score + Vulnerability Detail Contracts (Sprint 20260304_309)

Delivered contracts:

- `src/Web/StellaOps.Web/src/app/features/security/vulnerability-detail.facade.ts`
  - Single API-backed facade for vulnerability detail loading and signed-score verification.
  - Consolidates route/malformed/not-found handling for both Security and Security-Risk route trees.
- `src/Web/StellaOps.Web/src/app/features/security/vulnerability-detail-page.component.ts`
  - No static CVE payloads. Reads route id and renders deterministic loading/error/not-found states.
  - Uses API-backed fields for CVSS/EPSS/KEV, environment impact, gate impact, and witness path.
- `src/Web/StellaOps.Web/src/app/features/security-risk/vulnerability-detail-page.component.ts`
  - Uses the shared Security vulnerability detail view; no placeholder text-only implementation remains.
- `src/Web/StellaOps.Web/src/app/shared/components/score/signed-score-ribbon.component.ts`
  - Reusable signed-score ribbon for vulnerability and triage detail contexts.
  - Supports collapsed/expanded factor breakdown, provenance links, verify action, and policy gate badge (`pass|warn|block`).
  - Reuses existing shared score primitives (`ScorePillComponent`, `ScoreBadgeComponent`) instead of duplicating score visuals.

Scanner replay route contract (Web client):

- Implemented by `src/Web/StellaOps.Web/src/app/core/api/proof.client.ts` (`ScoreReplayClient`).
- Canonical paths:
  - `POST /api/v1/scans/{scanId}/score/replay`
  - `GET /api/v1/scans/{scanId}/score/bundle`
  - `POST /api/v1/scans/{scanId}/score/verify`
  - `GET /api/v1/scans/{scanId}/score/history`
- Compatibility aliases remain backend-side (`/api/v1/score/{scanId}/...`) while clients migrate, but Web now uses canonical scanner routes.

Coverage:

- `src/Web/StellaOps.Web/src/app/core/api/proof.client.spec.ts`
- `src/Web/StellaOps.Web/src/tests/sprint309/signed-score-ribbon.component.spec.ts`
- `src/Web/StellaOps.Web/src/tests/sprint309/security-vulnerability-detail-page.component.spec.ts`
- `src/Web/StellaOps.Web/src/tests/sprint309/security-risk-vulnerability-detail-page.component.spec.ts`

Remaining planned FE capability (explicitly still planned):

- Signed-score ribbon integration into additional triage detail canvases beyond vulnerability detail routes (not in sprint 309 scope).