299 lines
14 KiB
Markdown
299 lines
14 KiB
Markdown
# 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).
|