SDS-054: Workbench UI Service

metadata: id: SDS-054 title: Workbench UI Service status: Draft version: 1.0.0 bounded_context: developer-tooling satisfies: - PRD-025 - ADR-033 date_created: 2025-12-31 last_updated: 2025-12-31 —

Purpose

Provide an operator/developer Workbench UI for inspecting semantic state, viewing governance evidence, and executing privileged operations while respecting kernel-shell architecture constraints.

Architecture

Component Diagram

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

┌─────────────────────────────────────────────────────────────────┐
│                      Workbench UI Service                        │
│                     (Shell - No Domain Logic)                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Frontend Layer                         │   │
│  │  ┌────────────┐ ┌────────────┐ ┌────────────────────────┐│   │
│  │  │ KG Explorer│ │ Manifest   │ │ Governance Console     ││   │
│  │  │            │ │ Inspector  │ │                        ││   │
│  │  └────────────┘ └────────────┘ └────────────────────────┘│   │
│  │  ┌────────────┐ ┌────────────┐ ┌────────────────────────┐│   │
│  │  │ Simulation │ │ Observ.    │ │ Ops Actions            ││   │
│  │  │ Cockpit    │ │ Dashboard  │ │                        ││   │
│  │  └────────────┘ └────────────┘ └────────────────────────┘│   │
│  │  ┌────────────────────────────────────────────────────┐  │   │
│  │  │ Case Management Console                             │  │   │
│  │  └────────────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────────┘   │
│                              │                                   │
│                              ▼                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    BFF (Backend-for-Frontend)             │   │
│  │  ┌────────────┐ ┌────────────┐ ┌────────────────────────┐│   │
│  │  │ Auth       │ │ Query      │ │ Action Dispatcher      ││   │
│  │  │ Middleware │ │ Aggregator │ │                        ││   │
│  │  └────────────┘ └────────────┘ └────────────────────────┘│   │
│  └──────────────────────────────────────────────────────────┘   │
│                              │                                   │
└──────────────────────────────┼───────────────────────────────────┘
                               ▼
          ┌────────────────────────────────────────┐
          │              Kernel APIs               │
          │  SDS-003 │ SDS-012 │ SDS-047 │ SDS-053 │
          └────────────────────────────────────────┘

Shell Constraints (ADR-033)

  1. No domain logic — All business rules live in kernel services
  2. Stateless — No session state beyond JWT token
  3. Translate only — Convert UI actions to kernel commands/queries
  4. Fail-safe — Graceful degradation when kernel unavailable

Frontend Modules

KG Explorer Module

Feature Description
Entity Search Full-text + property-based entity search
Graph Visualization Force-directed layout for relationship exploration
Entity Detail Panel Property viewer + policy annotations
Relationship Navigator Follow links between entities 
1
2
3
4
5
6
7
8

interface KGExplorerState {
  searchQuery: string;
  selectedEntity?: EntityId;
  visibleNodes: EntityNode[];
  visibleEdges: RelationshipEdge[];
  zoomLevel: number;
  centerPosition: { x: number; y: number };
}

Manifest Inspector Module

Feature Description
Manifest Browser Tree view of manifest structure
Source Tracing Link back to SEA-DSL source
Diff View Compare manifest versions
Provenance Display Generation metadata + hash

Governance Console Module

Feature Description
Compliance Dashboard Policy pass/fail overview
Violation List Filterable violation browser
Evidence Export Download evidence bundles
Policy Viewer Inspect policy definitions

Operational Actions Module

Feature Description
Action Catalog Available privileged operations
Authorization Gate Pre-flight auth check display
Audit Trail Recent action history
Confirmation Dialog Multi-step approval for sensitive ops

Case Management Console Module

Integrates with SDS-012 (Case Management Service) to provide case lifecycle visibility.

Feature Description
Case Dashboard Active + historical cases with status breakdown (Open/In-Progress/Closed)
Case Browser Filterable list with stage/milestone view and CMMN lifecycle states
Task Queue Assigned tasks with status (Available/Active/Completed/Terminated)
Artifact Pipeline Trace artifact reification: Cognitive → Intellectual → Product → Capital
Case Timeline Chronological view of transitions and events per SDS-012 TransitionToken 
1
2
3
4
5
6
7
8
9
10
11

interface CaseConsoleState {
  caseFilter: {
    status: ('open' | 'active' | 'completed' | 'terminated')[];
    includeHistorical: boolean; // Default: true
    dateRange?: { start: Date; end: Date };
  };
  selectedCaseId?: CaseId;
  visibleCases: CaseSummary[];
  taskQueue: TaskItem[];
  artifactPipeline: ArtifactStage[];
}

BFF (Backend-for-Frontend)

Endpoints

Query Endpoints

Endpoint Method Description
/api/kg/entities GET Search entities
/api/kg/entities/:id GET Get entity details
/api/kg/graph GET Get visualization subgraph
/api/manifests GET List manifests
/api/manifests/:id GET Get manifest details
/api/governance/dashboard GET Compliance summary
/api/governance/violations GET List violations
/api/governance/evidence/:id GET Export evidence

Case Management Endpoints

Endpoint Method Description
/api/cases GET List cases (filter: status, date, historical)
/api/cases/:id GET Case details + stages + milestones
/api/cases/:id/tasks GET Tasks for case (filter: status, assignee)
/api/cases/:id/artifacts GET Artifact pipeline state
/api/cases/:id/timeline GET Case transitions (per SDS-012 TransitionToken)
/api/cases/dashboard GET Aggregated case statistics

Action Endpoints

Endpoint Method Description Authorization
/api/actions/simulation/trigger POST Trigger simulation role:operator
/api/actions/governance/approve POST Approve change role:approver
/api/actions/break-glass POST Emergency override role:admin + 2FA

Authorization Middleware

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

interface AuthorizationCheck {
  requiredRole: Role;
  requiredScope?: Scope;
  requiresMFA?: boolean;
  auditLevel: "standard" | "elevated" | "critical";
}

// Maps action to authorization requirements
const actionAuthMap: Record<string, AuthorizationCheck> = {
  "simulation:trigger": {
    requiredRole: "operator",
    auditLevel: "standard",
  },
  "governance:approve": {
    requiredRole: "approver",
    auditLevel: "elevated",
  },
  "break-glass": {
    requiredRole: "admin",
    requiresMFA: true,
    auditLevel: "critical",
  },
};

Integration Points

System Integration Purpose
SDS-003 Knowledge Graph Service Entity queries, graph data
SDS-012 Case Management Service CMMN cases, tasks, artifacts
SDS-031 Authority Boundaries Authorization rules
SDS-047 GovernedSpeed™ Evidence, violations
SDS-048 Platform UI Integration Shared UI patterns
SDS-050 Semantic Identity Entity identity resolution
SDS-053 Simulation Service Cockpit integration
SDS-030 Observability Metrics dashboards

Security Model

Authentication

Authorization

Per SDS-031 Authority & Ownership Boundaries:

1
2
3
4
5
6
7
8
9
10
11
12
13

interface UserContext {
  userId: string;
  roles: Role[];
  scopes: Scope[];
  mfaVerified: boolean;
  sessionStart: DateTime;
}

// All privileged actions require:
// 1. Role membership
// 2. Scope inclusion (if applicable)
// 3. MFA verification (for critical actions)
// 4. Audit logging

Audit Logging

All actions logged with:

1
2
3
4
5
6
7
8
9
10
11

interface AuditEntry {
  timestamp: DateTime;
  userId: string;
  action: string;
  targetResource: string;
  result: "success" | "denied" | "error";
  reason?: string;
  correlationId: string;
  clientIp: string;
  userAgent: string;
}

UI/UX Guidelines

Layout

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

┌──────────────────────────────────────────────────────────┐
│  Logo   │  Search  │  Notifications  │  User Menu       │
├─────────┼──────────────────────────────────────────────┤
│         │                                               │
│  Nav    │              Main Content Area                │
│         │                                               │
│  • KG   │  ┌─────────────────────────────────────────┐  │
│  • Mani │  │                                         │  │
│  • Gov  │  │         Active Module View              │  │
│  • Ops  │  │                                         │  │
│  • Sim  │  │                                         │  │
│         │  └─────────────────────────────────────────┘  │
│         │                                               │
├─────────┴──────────────────────────────────────────────┤
│  Status Bar: Connection │ Kernel Health │ Last Sync     │
└──────────────────────────────────────────────────────────┘

Design Tokens

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

:root {
  /* Colors */
  --color-primary: #0066cc;
  --color-success: #28a745;
  --color-warning: #ffc107;
  --color-danger: #dc3545;

  /* Spacing */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;

  /* Typography */
  --font-mono: 'JetBrains Mono', monospace;
  --font-sans: 'Inter', sans-serif;
}

NFR Specifications

NFR Specification
Page Load < 2s for initial load, < 500ms for navigation
Graph Render 60fps for < 1K nodes, graceful degradation beyond
Accessibility WCAG 2.1 AA, keyboard navigation, screen reader support
Browser Support Chrome 100+, Firefox 100+, Safari 15+, Edge 100+

Implementation Notes

Technology Stack

1
2
3
4
5
6
7
8
9
10
11
12

frontend:
  framework: React 18 / Remix
  state: Zustand
  visualization: D3.js / react-force-graph
  styling: Tailwind CSS
  testing: Vitest + Testing Library + Playwright

bff:
  runtime: Node.js / Hono
  validation: Zod
  auth: jose (JWT)
  testing: Vitest

Build Configuration

1
2
3
4
5
6
7
8
9

# Nx project configuration
project:
  name: workbench-ui
  type: application
  tags:
    - scope:shell
    - type:app
  implicitDependencies:
    - platform-ui-integration
Type ID Document
ADR ADR-033 Kernel-Shell Architecture
PRD PRD-025 Workbench UI
PRD PRD-026 Case Management Platform
SDS SDS-003 Knowledge Graph Service
SDS SDS-012 Case Management Service
SDS SDS-031 Authority & Ownership Boundaries
SDS SDS-047 GovernedSpeed™ Governance Runtime
SDS SDS-048 Platform UI Integration
SDS SDS-050 Semantic Identity & Provenance