git.stella-ops.org/docs/modules/web/architecture.md

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. 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:

• Overlay controls only expose the live shipped overlay families policy, vex, and aoc.
• The explorer route consumes GET /graphs/{graphId}/tiles?includeOverlays=true through GraphPlatformHttpClient.
• Canvas halo colors and summaries derive from live overlay payloads, with policy taking precedence over vex and aoc when multiple overlays exist for the same node.
• When a graph has no overlays, the shipped route shows explicit empty-state messaging rather than inventing reachability or simulation data.

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

3.8 Active-Surface Verification Lane and Setup Wizard Styling (Sprint 20260405_002 / 005)

Focused verification and bundle-polish notes for the shipped surfaces:

• The repo now carries a dedicated active-surface test lane: ng run stellaops-web:test-active-surfaces (also exposed as npm run test:active-surfaces).
• The lane intentionally covers the currently shipped Graph, Evidence, deployment creation, vulnerability detail, and environment-detail flows instead of the broader legacy spec backlog.
• The setup wizard and step-content styling moved from oversized inline component styles into global SCSS under src/Web/StellaOps.Web/src/styles/ so the production build clears anyComponentStyle budgets without raising those budgets.
• Touched shipped routes continue to use explicit live empty/error/unavailable states rather than mock action fallbacks.

---

4) Authentication

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

---

5) Configuration

// 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).