Web

Status: Implemented Source: src/Web/ Owner: UI Guild

Note: This folder documents triage-specific frontend features. For the comprehensive Web UI architecture, see ../ui/architecture.md.

Purpose

Web provides the Angular 21 single-page application (SPA) frontend for StellaOps. Delivers the user interface for vulnerability exploration, policy management, scan results, SBOM visualization, release control, evidence/assurance, and administrative functions. The SPA is served by the router gateway as static assets and talks to backend services through gateway-routed APIs.

Components

Application:

• StellaOps.Web - Angular 21 SPA (standalone components, Angular Signals state, built-in control flow), TypeScript 5.9, Angular Material 21 + Angular CDK 21, built with the esbuild-based @angular/build:application builder. Source: src/Web/StellaOps.Web/.

Technology stack (from src/Web/StellaOps.Web/package.json and AGENTS.md):

• Framework: Angular 21.1.x (standalone components + Signals)
• Language: TypeScript 5.9
• UI: Angular Material 21 + Angular CDK 21
• Visualization: D3, Mermaid, Graphviz (@viz-js/viz), Monaco editor, ngx-markdown
• Unit tests: Vitest (via the @angular/build:unit-test builder; Jasmine compatibility shim in src/test-setup.ts)
• E2E tests: Playwright
• Component workshop: Storybook 10 (@storybook/angular)

Top-level navigation pillars (from src/app/core/navigation/navigation.config.ts; five-pillar IA per SPRINT_20260707_006, UIF-5 first-level limits per SPRINT_20260711_002):

• Home (Dashboard) — /
• Vulnerabilities (Exposure, Images, Intelligence) — /security
• Deployment (Releases: My services/Components/Bundles; Promotions: Approvals/Deployments/Gate policies; Environments: Readiness/Topology & hosts) — /releases, /environments, /developer, /ops/platform-setup
• Proof (Chain contextualizes custody, Verify, Proof Chains, Audit incl. Exports/Bundles; Estate; Compliance: NIS2/DORA/CRA) — /evidence, /ops/operations/audit, /assurance
• Operate — four first-level shelves: Operations, Connections, Access, Settings. Shelf links resolve to the first scope-visible child; retained routes remain available beneath them — /ops, /inventory, /setup, /console-admin
• User Preferences (user menu) — /settings

Each first-level nav item renders a short inline sublabel plus a full-sentence hover tooltip (SidebarTooltipDirective); demoted routes (/evidence/exports, /evidence/bundles, /evidence/transparency, /setup/security-data, /setup/tenant-branding, /setup/integrations/runtime-hosts) stay resolvable for deep links but have no duplicate sidebar entry.

Key Features:

• Dashboard and mission-control overview (default route loads DashboardV3Component)
• Container scan results and SBOM explorer
• Vulnerability Database browser backed by Concelier /api/v1/advisories with server-side paging and source/severity/date/free-text filters; its Sources & consensus detail reads /api/v1/issues and lazily exposes each product’s gate-decision winner, losing alternatives, ranks, and decision hash
• Policy editor / Policy Studio and governance workflows
• VEX statement review and approval workflows
• Release Orchestrator: components, environments/targets, execution plugins, promotions, bundles
• Evidence / assurance: capsules, exports, verify-replay, audit log
• Admin console (Authority /console/admin/* APIs) for tenants, users, roles, clients, tokens, branding, and identity providers
• Setup wizard for first-run platform bootstrap
• Unified Triage Experience - Smart-Diff Compare View, Triage Canvas, Risk Dashboard
• Risk Budget Visualization - Burn-up charts, heatmaps, exception ledger

Configuration

The SPA is configured at runtime (not build-time), so a single bundle can serve any deployment. AppConfigService (src/app/core/config/app-config.service.ts) resolves configuration through this chain:

1. ?envSettings=<url> query param (stored in the stellaops_env_settings_url cookie)
2. /platform/envsettings.json (primary; served by the Platform service through the gateway)
3. /config.json (legacy fallback; a stub ships under src/config/config.json)

There is no STELLAOPS_BACKEND_URL environment variable — backend endpoints come from the resolved config document. The config shape is defined by the AppConfig interface in src/app/core/config/app-config.model.ts:

• authority — OIDC settings: issuer, clientId, authorizeEndpoint, tokenEndpoint, optional logoutEndpoint, redirectUri, optional silentRefreshRedirectUri/postLogoutRedirectUri, scope (space-delimited), audience, optional dpopAlgorithms (ES256/ES384/EdDSA, default ES256), optional refreshLeewaySeconds (default 60)
• apiBaseUrls — per-service base URLs: required scanner, policy, concelier, attestor, authority; optional gateway, ledger, vex, signals, excitor, notify, scheduler
• telemetry (optional) — otlpEndpoint, sampleRate
• welcome (optional) — title, message, docsUrl
• doctor (optional) — fixEnabled
• setup (optional) — Platform setup state (undefined = fresh install, "complete", or a resume step id)
• quickstartMode — deprecated and ignored at runtime (kept only for deserialization compatibility)

Module/feature visibility is scope-gated by route guards (requireScopesGuard / requireAnyScopeGuard in src/app/app.routes.ts), not by config feature flags. Scopes are the canonical OAuth scopes from StellaOps.Auth.Abstractions/StellaOpsScopes.cs (e.g. ui.read, release:read, scanner:read, vuln:view, ui.admin).

angular.json and tsconfig*.json hold the build-time Angular/TypeScript configuration.

Build and Development

Working directory: src/Web/StellaOps.Web/. Exact script wiring is in package.json.

# Install dependencies (deterministic / offline-friendly)
npm run ci:install          # npm ci --prefer-offline --no-audit --no-fund

# Development server (runs node scripts/serve.js, not `ng serve` directly)
npm start

# Production build (ng build → dist/stellaops-web/)
npm run build

# Run unit tests (Vitest, batched via scripts/run-unit-test-batches.mjs)
npm test                    # CI variant: npm run test:ci (adds the bundle-mutation guard)

# Run E2E tests (Playwright, auto-starts the test dev server on 127.0.0.1:4400)
npm run test:e2e

Notes:

• npm start runs the custom scripts/serve.js; for local work against the Docker stack, prefer the devops/compose/docker-compose.dev-ui.yml override (zero-restart) described in src/Web/StellaOps.Web/AGENTS.md.
• The dev server binds http://localhost:4200/ by default; the Playwright test server binds 127.0.0.1:4400.
• Storybook: npm run storybook / npm run storybook:build.

Dependencies

• Gateway (API access)
• Authority (authentication and authorization)
• All backend services (via Gateway routing)

Related Documentation

Triage Experience

• Unified Triage Specification - Consolidated triage requirements
• Smart-Diff UI Architecture - Compare view design
• Triage Component Catalog - Angular component documentation
• Competitive Triage Patterns - Industry comparison

Module Dependencies

• UI Module: ../ui/(shared UI components and Web architecture)
• Router/Gateway: ../router/(API access and routing)
• Authority: ../authority/(authentication and authorization)
• Findings Ledger: ../findings-ledger/(vulnerability findings data; VulnExplorer is consolidated under Findings)

Implementation Sprints (archived)

These sprints have shipped and been archived; links point to docs-archive/implplan/.

• Smart-Diff Compare
• Triage Canvas
• Risk Dashboard

Current Status

Angular 21 SPA implemented with lazy-loaded routing, OIDC/DPoP authentication, runtime configuration, and scope-gated route guards. Supports vulnerability exploration/triage, scan results, SBOM visualization, policy management, release control, evidence/assurance, and console administration. Unit tests run on Vitest (@angular/build:unit-test); Playwright E2E and Storybook are configured.