generated from coulomb/repo-seed
95 lines
5.3 KiB
Markdown
95 lines
5.3 KiB
Markdown
# UI and Operator Console Spec
|
|
|
|
## Purpose
|
|
|
|
Define the Core Hub operator interface without coupling the framework to one UI runtime.
|
|
|
|
## UI Direction
|
|
|
|
- Use whynot-design tokens and component semantics where possible.
|
|
- 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.
|
|
|
|
## Console Information Architecture
|
|
|
|
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.
|
|
|
|
| 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 |
|
|
|
|
## Screen Model
|
|
|
|
Every screen should expose the same operational primitives:
|
|
|
|
- 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.
|
|
|
|
|
|
## First Prototype
|
|
|
|
The first prototype is a protected server-rendered route at `/console`. It uses the existing FastAPI runtime, inline whynot-aligned tokens/classes, and the current SQLAlchemy read model to show:
|
|
|
|
- readiness gates;
|
|
- hub registry rows;
|
|
- migration run ledger rows;
|
|
- non-secret API consumer metadata;
|
|
- recent interaction events.
|
|
|
|
The route requires the same bearer-token authentication as protected `/api/v2` resources. It intentionally renders only API key prefixes and non-secret lifecycle metadata.
|
|
|
|
## 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.
|