Files

master 17419ba7c4 doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements

2026-01-19 09:02:59 +02:00

12 KiB

Raw Blame History

UI Rework Architecture - Release Control Plane

Ownership: UI Guild, Platform Team Status: Planned Related: Current UI Architecture, Wireframes, Migration Map

This document defines the target UI architecture for Stella Ops as an evidence-based release control plane with hybrid reachability as a first-class gate and explanation layer.

0) Vision Summary

The current UI tells users "scanner + admin console." The new UI must communicate:

"What is deployed where" (by digest, per environment/target)
"What is allowed to ship next" (promotion requests + approvals)
"Why it is allowed/blocked" (policy gates + reachability evidence)
"Where the evidence is" (one-click proof chain and export)

Everything else (vuln explorer, SBOM graph, VEX hub, feeds, ops health) is supporting detail.

1) New UX Mental Model

1.1 Core Objects (first-class nouns everywhere)

Object	Description
Release	Bundle of component-to-digest mappings (immutable identity)
Environment	Dev/QA/Staging/Prod (policies, windows, approvals)
Promotion	Request to move a Release to an Environment
Deployment	Execution instance (workflow run against targets)
Evidence Packet	Signed bundle of inputs/outputs of a decision/run

1.2 Core Jobs (UI must optimize for these first)

Ship a release: create -> request promotion -> approve -> deploy
Explain/justify a decision: why allowed/blocked + evidence
Operate with confidence: drift, CVE updates, replay, audit export

2) Information Architecture

2.1 Current Top-Level Nav (scanner-centric)

HOME / ANALYZE / TRIAGE / POLICY / OPS / NOTIFY / ADMIN

2.2 New Top-Level Nav (release control plane)

CONTROL PLANE / RELEASES / APPROVALS / SECURITY / EVIDENCE / OPERATIONS / SETTINGS

New Section	Contains	Replaces
Control Plane	Pipeline overview, Action Inbox, Pending Promotions, Drift/Risk	Home dashboard
Releases	Release list, Release detail, Environment detail	Release Orchestrator (hidden)
Approvals	Approval inbox, Approval detail	Release Orchestrator approvals
Security	Overview, Findings, Vulnerabilities, SBOM Graph, VEX, Exceptions	Analyze + Triage + VEX Hub
Evidence	Packets, Proof Chains, Replay/Verify, Export, Audit Bundles	Scattered evidence views
Operations	Orchestrator, Quotas, Dead-letter, SLO, Health, Feeds, Scheduler	Ops/* + Scheduler
Settings	Integrations, Trust, Admin, Notifications, Policy Governance	Console/Admin + scattered config

3) Shell & Layout Architecture

3.1 Shell Blueprint

+------------------------------------------------------------------------------+
| Stella Ops   [Global Search: release|digest|CVE|env]   [Tenant] [User]       |
| Offline: OK | Feed Snapshot: 2026-01-15 | Policy: v3.1 | Evidence: ON        |
+---------------+--------------------------------------------------------------+
| CONTROL PLANE | Breadcrumb: Section > Page                                   |
| RELEASES      |                                                              |
| APPROVALS     |  <router-outlet>                                             |
| SECURITY      |                                                              |
| EVIDENCE      |                                                              |
| OPERATIONS    |                                                              |
| SETTINGS      |                                                              |
+---------------+--------------------------------------------------------------+

3.2 Shell Components

Component	Responsibility
`AppShellComponent`	Top-level layout with topbar + sidebar + outlet + overlay hosts
`AppTopbarComponent`	Global search, tenant context, status chips, user menu
`AppSidebarComponent`	Left navigation rail with nav groups and items
`BreadcrumbComponent`	Context-aware breadcrumbs from router data
`GlobalSearchComponent`	Unified search across releases, digests, CVEs, environments
`ContextChipsRowComponent`	Offline status, feed snapshot, policy baseline, evidence mode

4) Folder Structure (Angular 17+ Standalone)

src/app/
  core/                     # auth, api client, guards, nav config, app init
  layout/                   # app shell, sidebar, topbar, page scaffolding
  shared/
    ui/                     # design system primitives (buttons, chips, tables)
    domain/                 # domain widgets (digest chip, gate badges, evidence link)
    overlays/               # drawers/modals (evidence drawer, witness drawer)
    pipes/                  # formatting
    util/                   # helpers, comparators, trackBy fns
  features/
    control-plane/          # / - Control Plane Overview
    releases/               # /releases, /releases/:id
    approvals/              # /approvals, /approvals/:id
    environments/           # /environments, /environments/:id
    deployments/            # /deployments, /deployments/:id
    security/               # /security/*
    evidence/               # /evidence/*
    reachability/           # /witness/:id
    operations/             # /operations/*
    settings/               # /settings/*

5) Shared Domain Widgets (The Moat UI)

These components encode Stella's differentiators and must be consistent everywhere.

5.1 Digest Identity

Component	Inputs	Behavior
`DigestChipComponent`	`digest`, `label?`, `variant`	Short digest display, copy on click, full on hover
`BundleDigestHeaderComponent`	`releaseId`, `bundleDigest`, `createdAt`, `sourceRef`	Release identity block

5.2 Gate System

Component	Inputs	Behavior
`GateBadgeComponent`	`state`, `label`	PASS/WARN/BLOCK badges
`GateSummaryPanelComponent`	`gates[]`, `policyRef`, `snapshotRef`	Compact gate list with drill-down
`GateExplainDrawerComponent`	`gateRunId`	K4 lattice explanation, rule hits, evidence

5.3 Evidence UX

Component	Inputs	Behavior
`EvidenceLinkComponent`	`evidenceId`, `type`, `verified`, `signed`	Consistent evidence link
`EvidencePacketSummaryComponent`	`EvidencePacketHeaderVM`	Who/What/Why/How/When audit block
`ProofChainLinkComponent`	`subjectDigest`	Standard proof chain entry

5.4 Reachability Witness

Component	Inputs	Behavior
`ReachabilityStateChipComponent`	`state`, `confidence`	Reachable/Unreachable/Uncertain + confidence
`WitnessPathPreviewComponent`	`path[]`, `guards`, `deterministic`	Call path preview with drill-down
`WitnessViewerComponent`	`witnessId`	Full witness page with exports and replay

6) Flagship Pages

6.1 Control Plane Overview (`/`)

Goal: Answer in one screen: what's deployed, what's pending, what changed, what needs attention.

Components:

EnvironmentPipelineWidgetComponent - Dev -> QA -> Staging -> Prod visualization
ActionInboxWidgetComponent - Pending approvals, blocked promotions, failed deployments
DriftRiskDeltaWidgetComponent - CVE updates, feed staleness, config drifts
PendingPromotionsTableComponent - Release promotions waiting for action

6.2 Release Detail (`/releases/:releaseId`)

Goal: One flagship screen tying promotion + gates + reachability + evidence + proof chain.

Tabs:

Overview (deployment map, gate summary, security impact, latest evidence)
Components (digest inventory)
Gates (detailed policy evaluation)
Promotions (promotion history)
Deployments (deployment runs)
Evidence (linked evidence packets)
Proof Chain (full proof chain viewer)

6.3 Approval Detail (`/approvals/:approvalId`)

Goal: Everything needed to make a decision without navigating away.

Panels:

Diff-first panel (what changed)
Gates panel (expandable gate results)
Decision panel (approve/reject/comment)
Reachability Witness panel (the moat)
Evidence quick panel

6.4 Evidence Packet Viewer (`/evidence/:evidenceId`)

Goal: Evidence as structured "who/what/why/how/when" record + bundle contents + verify.

Sections:

Summary (audit-friendly header)
Contents (SBOM, verdict, witness slice, VEX, attestations)
Verification (signature + Rekor inclusion proofs)

7) State Management

7.1 Signal Store Pattern

Each major page/container has a dedicated store service:

@Injectable()
export class ReleaseDetailStore {
  private state = signal<ReleaseDetailState>({ ... });

  release = computed(() => this.state().release);
  gateSummary = computed(() => this.state().gateSummary);

  load(releaseId: string) { /* triggers effects + sets loading/error */ }
  refresh() { /* re-runs queries */ }
  requestPromotion() { /* command method */ }
}

7.2 Cross-Cutting Stores

Store	Responsibility
`AppContextStore`	Tenant, user, offline mode, feed snapshot, evidence mode
`GlobalSearchStore`	Query -> aggregated results across types
`OverlayStore`	Open/close drawers (evidence, witness, gate explain)

8) Overlays (Drawers/Modals)

Essential for "small pages, deep drill-down" requirement:

Overlay	Purpose
`EvidencePacketDrawerComponent`	Opens from anywhere; condensed evidence view
`WitnessDrawerComponent`	Preview witness path + quick export + open full
`GateExplainDrawerComponent`	K4 lattice reasoning + rule hits + evidence anchors
`CreateReleaseModalComponent`	New release creation flow
`RequestPromotionModalComponent`	Promotion request flow
`RollbackModalComponent`	Rollback confirmation
`RequestExceptionModalComponent`	Exception request flow

9) UX Contracts

9.1 Gate State Presentation

State	Badge	Color
PASS	`[PASS]`	Green
WARN	`[WARN]`	Amber
BLOCK	`[BLOCK]`	Red

Always show with one-line reason.

9.2 Reachability State Presentation

State	Display
Reachable	State + Confidence + Witness link
Unreachable	State + Confidence (0.90+)
Uncertain	State + Confidence + "why uncertain" + resolution hints

9.3 Digest Visibility

Show short digest everywhere (sha256:abc...123)
Full digest on hover/copy
Copy buttons for operational fields

9.4 Evidence Traceability

Policy baseline version shown where decisions are made
Feed snapshot version shown where decisions are made
"Open Evidence" and "Open Proof Chain" always one click away

10) Implementation Priority

Phase 1 (Highest ROI)

Make / the Control Plane Overview (pipeline + inbox + drift)
Consolidate Settings (stop configuration fragmentation)
Make Approvals evidence-first with reachability witness (moat on display)

Phase 2 (Core Product)

Shell & navigation redesign (left rail)
Releases feature (list + detail flagship)
Evidence unification

Phase 3 (Polish)

Security consolidation (merge Analyze + Triage)
Environments & Deployments features
Route migration & legacy redirect telemetry

Wireframes - ASCII wireframes for flagship pages
Migration Map - Route migration from current to new IA
Component Breakdown - Detailed Angular component inventory
Current Architecture - Existing UI architecture reference

Last updated: 2026-01-18

12 KiB Raw Blame History