Hub Dashboard
Requirements & User Stories

As a Nexus platform user, I want to enter my email and engine address to access the hub dashboard, so that I can view all organisations I belong to.

Click Sequence

Acceptance Criteria

• AC-1: Email field is required; submitting empty shows inline error "Podaj adres e-mail."
• AC-2: Base URL defaults to http://localhost:8010 if empty
• AC-3: On API error, login status shows error message in red and re-enables login button
• AC-4: On success, hub screen renders within 500ms of API response

As a returning user, I want to have my last login details pre-filled, so that I can re-enter quickly without retyping.

Acceptance Criteria

• AC-1: Last successful login saves org_slug, api_key, and base URL to localStorage('nexus-login')
• AC-2: On page load, saved values are restored to form fields

As a user with a single org, I want to select an org from the dropdown and log in directly to the workspace, so that I skip the hub and enter my workspace immediately.

Click Sequence

As a platform administrator, I want to see real-time system health on the hub, so that I can identify issues before they affect users.

Components

• ServiceHealthDashboard: Chameleon component rendering health status from /health
• DashboardResourceMonitor: Chameleon component showing CPU, RAM, Disk, Uptime from /health/resources
• Sparkline: 24-hour pipeline activity histogram

Acceptance Criteria

• AC-1: Health data refreshes every 10 seconds via polling interval
• AC-2: Resource monitor displays 4 metrics: CPU %, RAM %, Disk %, Uptime
• AC-3: Sparkline renders a bar chart proportional to pipeline run counts
• AC-4: Version badge shows engine version from /health response
• AC-5: Component version pills display individual component versions (Engine, Chameleon, deltaPrism, Admin) as pill badges in the page footer (not below the health widget). Each pill shows component name + semver from /health component_versions object. Pill colour matches component category (green=core, purple=UI, blue=data, orange=admin). Deployment type indicator (docker/bare-metal/cloud) shown as small icon prefix on each pill. (Requirement source: user verbal, 2026-05-04; supersedes earlier spec text "below the system health section" — ISSUE-024)

As a multi-org user, I want to see all my organisations as visual cards with key stats, so that I can quickly identify which workspace to enter.

Click Sequence

Acceptance Criteria

• AC-1: Cards use glassmorphism panel styling (.glass-panel)
• AC-2: Staggered reveal animation: each card fades in with 80ms delay increment
• AC-3: Clicking a card writes sessionStorage['na-session-skin'] (user preference, not org brand skin) then calls navigateToManagement(orgData) which opens APP_MGMT.html?org=SLUG — no ?skin= in URL (REQ-MGMT-001). Direct workspace entry is via the Open App button on the App Management page.
• AC-4: If user has no orgs, shows "Brak przypisanych organizacji." message
• AC-5: Card initials derived from first 2 characters of org name, uppercase
• AC-6: Each card shows a component pills row (below the stats row) listing the components active for that org's use-case (sourced from usecase.components field on the org object). Pills styled as small monospace badges. If usecase.components is absent or empty, the pills row is hidden. (User requirement added 2026-05-04, ISSUE-024)

As a user, I want to choose from 6 visual themes, so that I can personalise the dashboard appearance.

Click Sequence

Available Skins

As a Polish or English speaker, I want to toggle the UI language, so that I can use the dashboard in my preferred language.

Acceptance Criteria

• AC-1: Toggle button shows current language code (PL/EN)
• AC-2: Clicking toggles between Polish and English
• AC-3: All UI strings with data-i18n attribute update immediately
• AC-4: Selection persists to localStorage('nexus-lang')
• AC-5: Default language is Polish (pl)

As a stakeholder, I want to see product roadmap progress on the hub, so that I understand what is being built and when.

Acceptance Criteria

• AC-1: Roadmap sidebar shows items with: title, ETA, progress bar, task count (N/M), description
• AC-2: Progress bar fills proportionally to percentage value
• AC-3: Items reveal with staggered animation on hub load
• AC-4: v1 uses static data array; future versions will fetch from /hub/roadmap API

As an operator, I want to see recent system events, so that I have situational awareness of platform activity.

Acceptance Criteria

• AC-1: Timeline shows recent events with description text and relative timestamp
• AC-2: Events display in reverse chronological order
• AC-3: v1 uses static data array; future versions will fetch from /hub/activity API

As a user, I want to click an org card to open its management page, so that I can manage environments and navigate to the live application from one place.

Click Sequence

Acceptance Criteria

• AC-1: Clicking card body navigates to APP_MGMT.html?org=X — does NOT enter workspace directly (REQ-MGMT-001)
• AC-2: RMB on card (contextmenu event) shows context menu with “Open App” as a direct workspace entry option (REQ-RMB-001)
• AC-3: On auth failure from management page, user is returned to hub with error message
• AC-4: Demo banner shows when navConfig.demo_mode === true
• AC-5: Org name in app header comes from navConfig.app_title

As a workspace user, I want to navigate between views via a sidebar, so that I can access different pipelines within the org.

Acceptance Criteria

• AC-1: Sidebar items grouped by section (main, actions, pipeline) with visual separators
• AC-2: Each item shows SVG icon (from ICON_SVGS registry) + label text
• AC-3: Active item highlighted with accent color and background
• AC-4: Optional badge count displayed as pill on right side
• AC-5: Clicking item resets navStack and loads pipeline view
• AC-6: Items without pipeline_slug are disabled

As a user, I want to see pipeline outputs rendered as KPI dashboards, so that I can visualise data without configuring anything.

Acceptance Criteria

• AC-1: DashboardNode outputs render as KPI card grids
• AC-2: Each KPI card shows: label, value, optional trend indicator
• AC-3: Data tables render below KPIs with column headers from keys
• AC-4: Tables support sorting by column click

As a user, I want to see pipeline outputs as sortable tables, so that I can browse and sort structured data.

Acceptance Criteria

• AC-1: ListViewNode renders as full-width table with header row
• AC-2: Columns derived from first row keys of output data
• AC-3: Column headers are clickable for sort toggle (asc/desc)
• AC-4: Row click triggers drill-down if configured in node output

As a user, I want to fill in dynamic forms generated from pipeline schemas, so that I can submit data to pipelines without developer intervention.

Click Sequence

Acceptance Criteria

• AC-1: ChameleonForm component used for rendering (React)
• AC-2: Schema supports: text, number, select, textarea, date, boolean fields
• AC-3: Validation messages shown inline on submit failure
• AC-4: Form-only pipelines do not execute on initial load (render-only)

As a pipeline approver, I want to see pending approvals and provide decisions, so that gated pipelines can proceed past human checkpoints.

Acceptance Criteria

• AC-1: Pipeline status awaiting_approval renders dedicated gate view
• AC-2: Pipeline status awaiting_human renders human-input view
• AC-3: Pipeline status revision_requested renders revision feedback view
• AC-4: Approve/reject actions re-execute pipeline with decision payload

As a developer or admin, I want to see pipeline execution history in a side panel, so that I can debug issues and track run performance.

Click Sequence

Acceptance Criteria

• AC-1: Panel toggles via .open class on #run-panel
• AC-2: Each run entry shows: pipeline name, status badge (success/error/pending), duration in ms
• AC-3: Node logs show individual node execution times and outputs
• AC-4: Requirement reference: M-NEXUS-E3-3

As a user in any context, I want to access quick navigation actions from a floating button, so that I can return to hub, open logs, or switch theme without finding menu items.

Acceptance Criteria

• AC-1: FAB renders as Chameleon React component (NexusFab)
• AC-2: Trigger shows "N" character, opens radial menu on click
• AC-3: Menu items: Hub (return), Orchestrator (external link), Logs (toggle panel), Skin (cycle to next)
• AC-4: Closes on outside click via document event listener
• AC-5: Each menu item shows icon letter + label + description

As a workspace user, I want to return to the hub dashboard at any time, so that I can switch organisations or check system-wide status.

Acceptance Criteria

• AC-1: Triggered via FAB "Hub" action
• AC-2: App shell hides, hub screen shows
• AC-3: Org theme CSS cleared (hub skin re-applies)
• AC-4: Health polling restarts at 10s interval
• AC-5: Reveal animations re-trigger

As a Nexus operator, I want the canvas to be blank when I open the Orchestrator, so that I can see a clean state before selecting an org and pipeline.

Acceptance Criteria

• AC-1: On page load, LEVELS[0].nodes and LEVELS[0].edges are empty arrays — no demo or hardcoded data visible
• AC-2: Canvas renders an empty grid (no node cards, no edges)
• AC-3: Log bar shows "Wybierz org i pipeline" (Polish: Select org and pipeline)
• AC-4: If ?org= URL param is present, the org dropdown auto-selects that org and loadPipelines() fires — canvas remains blank until a pipeline is also selected
• AC-5: If ?org= and ?pipeline= URL params are both present, the matching pipeline is auto-selected and its graph is loaded into the canvas

As a Nexus operator, I want the pipeline dropdown to populate when I select an org, so that I can choose which pipeline to view or edit.

Acceptance Criteria

• AC-1: Selecting an org in the dropdown calls GET /pipelines?org_slug={slug}
• AC-2: Pipeline dropdown is populated with all returned pipelines in format {name} [{status}]
• AC-3: If the API returns 0 pipelines, the dropdown shows only the placeholder "-- PIPELINE --" and the log shows "Brak pipeline dla {org}"
• AC-4: Changing the org clears the pipeline dropdown and clears the canvas
• AC-5: API errors are shown in the log bar — canvas is not modified

As a Nexus operator, I want the canvas to load the selected pipeline's graph when I choose a pipeline, so that I can inspect and edit it.

Acceptance Criteria

• AC-1: Selecting a pipeline calls GET /pipelines/{id} and renders the returned graph on the canvas
• AC-2: If the returned graph has 0 nodes, the canvas is cleared to blank and the log shows "Pipeline {name}: brak wezlow" — the previous canvas content is NOT preserved
• AC-3: If the API call fails (non-200), the log shows the error and the canvas is NOT modified (previous state retained)
• AC-4: The log shows the pipeline name, version, and node count on successful load
• AC-5: Graph nodes are rendered at the coordinates stored in the pipeline graph data — not at default positions

As a Nexus operator, I want the Orchestrator to use my API key automatically, so that I do not have to enter it manually every time.

Acceptance Criteria

• AC-1: If ?key= URL param is present, it is stored in localStorage['ww_api_key'] and used for all API calls — no prompt shown
• AC-2: If no ?key= param and no value in localStorage, the user is prompted once — the entered value is stored in localStorage
• AC-3: The KEY button allows the user to update the stored key at any time — pressing it shows the current key and allows replacement
• AC-4: All API calls use the stored key via X-API-Key header — never embedded in URL except for SSE streams

As a platform operator, I want to see a live health indicator on each hub card, so that I can spot degraded environments without opening the management page.

Acceptance Criteria

• AC-1: Each card shows a coloured dot + label: ONLINE (green), DEGRADED (amber), OFFLINE (red), UNKNOWN (grey)
• AC-2: Health state sourced from GET /orgs/{org_slug}/environments/production (active env status field)
• AC-3: Refreshed on the same 10-second polling interval as other hub data
• AC-4: Clicking the indicator navigates to the environment health detail on the App Management page

As a platform administrator, I want to manage all environments of an app from a dedicated page, so that I can control versions, lifecycle, and configuration without entering the live app.

Click Sequence

Acceptance Criteria

• AC-1: URL deep-link APP_MGMT.html?org=X&env=staging pre-selects the staging environment
• AC-2: Active skin from hub session is inherited via sessionStorage['na-session-skin'] — written by hub before navigation, read by APP_MGMT on load. No ?skin= URL param is used.
• AC-3: “Open App” button is a prominent CTA at the top of the page
• AC-4: Settings tab exposes the RMB Menu Editor (REQ-RMB-004)

As a DevOps operator, I want to start, stop, restart, backup, upgrade, and downgrade app environments, so that I can maintain deployment health and manage versions without CLI access.

Acceptance Criteria

• AC-1: Each environment row in the App Management page shows action buttons appropriate to its current status (running: Stop, Restart, Backup, Upgrade/Downgrade; stopped: Start)
• AC-2: Destructive actions (Stop, Downgrade on production) require a confirmation dialog stating the exact impact
• AC-3: Backup action triggers POST /orgs/{org_slug}/environments/{env_slug}/backup and shows a download link on completion
• AC-4: Upgrade/downgrade shows a diff summary of pipeline changes between the current and target version
• AC-5: Spin Up New Instance opens a dialog with name, base version selector, and confirm button

As a power user, I want to right-click a hub card to access the most common actions for that app, so that I can act quickly without navigating to the management page.

Click Sequence

Acceptance Criteria

• AC-1: Context menu styled in the active Nexus skin
• AC-2: Default 4 items always present and non-removable
• AC-3: Dynamic items loaded from GET /orgs/{org_slug}/rmb-items and cached in hub session
• AC-4: env_action type items show an inline confirmation mini-dialog before executing
• AC-5: Items with demo mode show DEMO pill and execute walkthrough without live backend call
• AC-6: Menu z-index is above all hub card content