StellaOps Console Architecture (Sprint 23)

Maps the Console implementation to the requirements captured in the Policy, Graph, Vulnerability Explorer, Orchestrator, and Notifications module documentation set.

Ownership: Console Guild • Docs Guild Delivery scope: StellaOps.Web Angular workspace, Console Web Gateway routes (/console/*), Downloads manifest surfacing, SSE fan-out for Scheduler & telemetry. Related docs: Console operator guide, Admin workflows, Air-gap workflows, Console security posture, Console observability, UI telemetry, Deployment guide

This dossier describes the end-to-end architecture of the StellaOps Console as delivered in Sprint 23. It covers the Angular workspace layout, API/gateway integration points, live-update channels, performance budgets, offline workflows, and observability hooks needed to keep the console deterministic and air-gap friendly.

1 · Mission & Boundaries

Non-goals: authoring ingestion logic, mutating Policy overlays, exposing internal database tables, or performing cryptographic signing in-browser.

2 · Workspace & Packages

The console is implemented in src/Web/StellaOps.Web, an Angular 17 workspace built on standalone components and Signals.

PathPurposeHighlights
src/app/core/authDPoP + PKCE authentication, Authority session store, HTTP interceptors.WebCrypto keygen (crypto.subtle), session metadata persisted in sessionStorage, DPoP nonce replay guard.
src/app/core/apiTyped API clients for Console gateway (/console/*) and downstream services.DTOs for Scanner, Notify, Concelier exporters; fetch-based clients with abort signals.
src/app/core/configRuntime configuration loader (/config.json), feature flag gating.Supports air-gap overrides and injects API base URLs, Authority issuer/client.
src/app/features/*Route-level shells (auth bootstrap, scans detail, notifications inbox, Trivy DB settings).Each feature is a standalone module with lazy loading and Angular Signals state.
src/app/testingFixtures and harnesses used in unit tests and storybook-like previews.Deterministic data used for Playwright and Vitest scenarios.

Workspace characteristics:

3 · Runtime Topology & Data Flow

The console SPA relies on the Console Web Gateway to proxy tenant-scoped API calls to downstream services. Tenant isolation and Aggregation-Only guardrails are enforced at every hop.

graph TD
    subgraph Browser["Browser (Angular SPA)"]
        UI[Console Shell
(Signals, Feature Modules)]
        SSE[EventSource / SSE Clients]
    end
    subgraph Gateway["Console Web Gateway"]
        Router[Minimal API / ASP.NET Core Router]
        StatusCache[Status Cache & Manifest signer]
    end
    Authority[Authority
(DPoP + PKCE)]
    Concelier[Concelier.WebService]
    Excititor[Excititor.WebService]
    Scheduler[Scheduler.WebService]
    Policy[Policy Engine API]
    SBOM[SBOM Service]
    Attestor[Attestor API]
    Downloads[Downloads Manifest Store]

    UI -->|/config.json| Gateway
    UI -->|/console/* (Bearer+DPoP)| Router
    SSE -->|/console/status/stream| Router
    Router --> Authority
    Router --> Concelier
    Router --> Excititor
    Router --> Scheduler
    Router --> Policy
    Router --> SBOM
    Router --> Attestor
    Router --> Downloads
    StatusCache -.-> Gateway
    Gateway -.-> UI

Key interactions:

4 · Live Updates & SSE Design

Live surfaces use HTTP/1.1 SSE with heartbeat frames to keep operators informed without polling storms.

EndpointPayloadSourceBehaviour
/api/console/status/streamstatusChanged, ingestionDelta, attestorQueue, offlineBanner eventsConcelier WebService, Excititor WebService, Attestor metrics5 s heartbeat; gateway disables proxy buffering (X-Accel-Buffering: no) and sets Cache-Control: no-store.
/api/console/runs/{id}/streamstateChanged, segmentProgress, deltaSummary, logScheduler WebService SSE fan-outEvent payloads carry traceId, runId, tenant; UI reconnects with exponential backoff and resumes using Last-Event-ID.
/api/console/telemetry/streammetricSample, alert, collectorStatusObservability aggregatorGated by ui.telemetry scope; disabled when CONSOLE_TELEMETRY_SSE_ENABLED=false.

Sequence overview:

sequenceDiagram
    autonumber
    participant UI as Console SPA
    participant GW as Console Gateway
    participant SCHED as Scheduler WebService

    UI->>GW: GET /api/console/runs/42/stream (Authorization + DPoP)
    GW->>SCHED: GET /runs/42/stream (X-StellaOps-TenantId)
    SCHED-->>GW: event: stateChanged data: {...}
    GW-->>UI: event: stateChanged data: {..., traceId}
    Note over UI,GW: Gateway injects retry-after + heartbeat every 15s
    UI-->>GW: (disconnect)
    UI->>GW: GET /console/runs/42/stream (Last-Event-ID: )
    GW->>SCHED: GET /runs/42/stream?since=

Offline behaviour:

5 · Performance & Budgets

SurfaceTargetEnforcement
First meaningful paint (dashboard)≤ 2.5 s on 4 vCPU offline runnerLighthouse CI gate (DEVOPS-CONSOLE-23-001), ui_route_render_seconds P95 alert.
Route hydration (feature shells)≤ 1.5 s after token acquisitionAngular Signals + lazy loading; route-level budgets tracked via custom telemetry.
Initial bundle sizeWarn ≥ 500 KB, fail ≥ 1 MBangular.json budgets; CI fails build on overflow.
Component stylesheetWarn ≥ 2 KB, fail ≥ 4 KBangular.json budgets; ensures Tailwind utilities stay tree-shaken.
SSE heartbeatEvery 15 s maxGateway emits comment heartbeats; UI resets timers on each frame.

Optimisation levers:

6 · Offline & Configuration Workflows

7 · Security & Tenancy

8 · Observability & Telemetry

9 · Integration Points & Dependencies

ServiceConsole dependencyNotes
AuthorityOIDC, DPoP tokens, tenant catalog, fresh-authRequires client console-ui with scopes listed in security guide.
Concelier WebService/console/advisories, feed health, export triggersGateway must enforce Aggregation-Only guardrails and surface merge hashes.
Excititor WebService/console/vex, consensus overlaysSSE ticker shows provider deltas.
Policy EngineFindings views, policy previews, simulation diffsConsole never writes overlays; uses effective_finding_* data via API.
Scheduler WebServiceRuns dashboard, SSE streams, queue metricsHeartbeat drives status ticker; cancellation actions require runs.manage.
SBOM ServiceSBOM explorer tree, component lookupResponses cached per tenant; offline bundles preload snapshots.
AttestorAttestation verification, evidence linksConsole displays verification status and CLI parity commands.
DevOps downloads pipelineSigned manifest for /console/downloadsManifest signatures validated with cosign key shipped in Offline Kit.
Release Orchestrator/api/v1/components, /api/v1/components/{id}/versions, /api/v1/components/{id}/sync-versions, /api/v1/release-orchestrator/environments/{id}/targets, /api/v1/release-orchestrator/execution-pluginsComponents workspace lists and edits registry-bound workload components, syncs tag-to-digest version maps, and pins selected component versions into release authoring without mock providers. Environment target forms include the current AnsibleHost connection shape (playbookBasePath, inventoryPath, optional defaultPlaybookPath, sshUsername, secret refs, and become settings). The installed-plugins page renders loaded execution-plugin diagnostics including capability, kind, trust, source, enabled state, and signature status.

10 · Compliance Checklist

Last updated: 2026-05-26 (Sprint 20260525.016 FEUI-003/FEUI-004 non-live updates).