# 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*