stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
17419ba7c4f8e35ed78033515115088eb40d20a7
git.stella-ops.org/docs/modules/ui/architecture-rework.md

327 lines
12 KiB
Markdown
Raw Blame History

# UI Rework Architecture - Release Control Plane
> **Ownership:** UI Guild, Platform Team
> **Status:** Planned
> **Related:** [Current UI Architecture](architecture.md), [Wireframes](guides/wireframes-flagship-pages.md), [Migration Map](guides/migration-map.md)
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:
1. **"What is deployed where"** (by digest, per environment/target)
2. **"What is allowed to ship next"** (promotion requests + approvals)
3. **"Why it is allowed/blocked"** (policy gates + reachability evidence)
4. **"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)
1. **Ship a release**: create -> request promotion -> approve -> deploy
2. **Explain/justify a decision**: why allowed/blocked + evidence
3. **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
```
### 2.3 Navigation Mapping
| 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:
```typescript
@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)
1. **Make `/` the Control Plane Overview** (pipeline + inbox + drift)
2. **Consolidate Settings** (stop configuration fragmentation)
3. **Make Approvals evidence-first with reachability witness** (moat on display)
### Phase 2 (Core Product)
4. Shell & navigation redesign (left rail)
5. Releases feature (list + detail flagship)
6. Evidence unification
### Phase 3 (Polish)
7. Security consolidation (merge Analyze + Triage)
8. Environments & Deployments features
9. Route migration & legacy redirect telemetry
---
## 11) Related Documentation
- [Wireframes](guides/wireframes-flagship-pages.md) - ASCII wireframes for flagship pages
- [Migration Map](guides/migration-map.md) - Route migration from current to new IA
- [Component Breakdown](guides/component-breakdown.md) - Detailed Angular component inventory
- [Current Architecture](architecture.md) - Existing UI architecture reference
---
*Last updated: 2026-01-18*
Reference in New Issue View Git Blame Copy Permalink