coulomb/core-hub
Archived
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Define Core Hub operator UI contract

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-27 13:39:13 +02:00
parent 0b90ebafd0
commit 6a2b9a9dde
4 changed files with 138 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
docs/specs/ui-operator-console.md
View File

@@ -10,22 +10,72 @@ Define the Core Hub operator interface without coupling the framework to one UI
- Prefer custom-element/Lit adapters for framework-neutral surfaces.
- Keep the canonical UI contract separate from generated or hand-authored implementation code.
- Use Playwright visual checks once UI components exist.
- Treat the console as an operational tool: dense, readable, stable, and built for repeated review.
## Initial Console Areas
## Console Information Architecture
- hub registry and health
- active workplans and blocked tasks
- progress/event stream
- messages and agent coordination
- decisions and deployment records
- API consumers and non-secret access metadata
- compatibility/migration dashboard
The first console should use a persistent shell with top-level operational areas. Each area maps to Core Hub API/resources so the UI can be implemented as server-rendered HTML, HTMX fragments, Lit components, or another thin adapter without changing the framework contract.
## Design Constraint
| Area | Purpose | Primary resources | Expected actions |
|---|---|---|---|
| Overview | Show system health, open blockers, recent progress, and readiness gates. | health, workplans, tasks, progress, migration runs | refresh, filter by severity, open linked record |
| Hub registry | Inspect hubs, active manifests, declared capabilities, widgets, and events. | hubs, hub capability manifests, widgets, interaction events | register hub, activate manifest, inspect capability |
| Workplans | Review active workplans, tasks, status drift, and human-needed items. | workplans, tasks, consistency reports | change task status, mark human review, open file reference |
| Event stream | Read recent interaction events, progress notes, and operational evidence. | interaction events, progress, outcome signals | filter by hub, task, event type, time window |
| Decisions | Browse decisions, deployment records, requirements, and evidence links. | decision records, deployment records, requirements | record decision, link evidence, mark superseded |
| Access | Manage API consumers and non-secret key metadata. | API consumers, API keys, policy scopes | create consumer, rotate key, disable consumer |
| Migration | Track Inter-Hub import readiness, migration bundles, row counts, discrepancies, smokes, rollback state. | migration runs, compatibility fixtures, deployment records | validate bundle, inspect dry-run, mark staging import reviewed |
| Messages | Coordinate agents and operators without exposing credentials. | messages, inbox, progress notes | read, reply, mark read, link to workplan |
The operator console is an operational tool. It should be dense, readable, and stable, not a marketing surface.
## Screen Model
## Open Questions
Every screen should expose the same operational primitives:
- Whether initial UI is server-rendered, Lit/custom-element, or a thin static frontend consuming FastAPI.
- Which Inter-Hub admin screens should be preserved as compatibility views vs. redesigned.
- title and short status line;
- filter controls for status, severity, source hub, owner, and time window where relevant;
- dense table or list body with stable columns;
- detail drawer or detail page for long JSON, evidence, and history;
- explicit empty, loading, stale, degraded, and unauthorized states;
- last refreshed timestamp and source API path;
- links back to backing workplan files when a record originates in git.
## Initial Navigation
1. Overview
2. Registry
3. Workplans
4. Events
5. Decisions
6. Access
7. Migration
8. Messages
9. System
`System` holds health, OpenAPI, consistency, release, and deployment diagnostics. It should not become a dumping ground for ordinary operator workflows.
## Data Exposure Rules
- Never render full API keys, raw tokens, database passwords, SSH material, or provider credentials.
- Render API key prefix, hash custody status, scopes, consumer status, creation time, and rotation status only.
- For migration bundles, render source, bundle hash, counts, warnings, and relationship diagnostics; do not render secrets from rejected payloads.
- Distinguish current state from imported historical state.
- Make uncertainty explicit with status labels such as `unverified`, `stale`, `degraded`, `blocked`, and `fallback`.
## Workflow Priority
The first useful prototype should implement read-heavy surfaces before mutation-heavy ones:
1. Overview with active blockers and readiness gates.
2. Registry read model for hubs, manifests, widgets, and events.
3. Migration dashboard for validation/import reports.
4. Access read model for consumers and key prefixes.
5. Workplan/task status view with file links.
6. Mutations for task status, manifest activation, consumer/key lifecycle, and decision records.
## Visual Posture
Use whynot-design quiet, document-like operational language: mostly neutral surfaces, strong typography hierarchy through labels and tables, no marketing hero, no decorative imagery, no gradients, no animation beyond basic hover/focus feedback. The console should feel like a control room notebook rather than a product landing page.
## Open Implementation Choice
The preferred first implementation is a thin FastAPI-served HTML/HTMX or static custom-element shell that consumes `/api/v2` and later Core Hub-native read endpoints. A heavier SPA should wait until the API and workflows prove the extra runtime is useful.