stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
9d8a2ad18196d66d592ae2cb43f06e36b39b43e2
git.stella-ops.org/docs/modules/web/architecture.md
master 50abd2137f Update docs, sprint plans, and compose configuration 
Add 12 new sprint files (Integrations, Graph, JobEngine, FE, Router,
AdvisoryAI), archive completed scheduler UI sprint, update module
architecture docs (router, graph, jobengine, web, integrations),
and add Gitea entrypoint script for local dev.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 08:53:50 +03:00

308 lines
15 KiB
Markdown
Raw Blame History

# 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:
- 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
```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).
Reference in New Issue View Git Blame Copy Permalink