Hub Dashboard
User Manual

End-user guide for the Nexus System Dashboard. Covers logging in, navigating the hub, entering workspaces, using the sidebar, submitting forms, managing themes, switching languages, and using the floating action button.

Prerequisites

You need:

• A modern browser (Chrome, Firefox, Edge, Safari)
• A Google account whose email has been granted access by a Nexus administrator
• Network access to the Nexus API (https://api.nexus-dev.codezerogroup.com)

Logging In — Google OAuth

1. Open NEXUS_APP.html in your browser
2. Click the "Sign in with Google" button
3. A Google login window opens — select your Google account or enter your email
4. Google redirects back to Nexus automatically — no password required
5. The Hub Dashboard loads showing your workspaces and navigation based on your role

What you see depends on your role

Your role	Navigation groups visible
Not logged in	None — login screen only
nexus_user	Documentation (User Manual, Node Registry)
nexus_admin	Strategy, Architecture, Use Cases, Platform, Documentation

Login Errors

If something goes wrong during login, the screen shows an error message. Common causes:

Error	Meaning	Action
token_exchange_failed	Google authorization code expired or was already used	Click “Sign in with Google” again to start a fresh login
invalid_state	Login session expired (too long between click and Google redirect)	Click “Sign in with Google” again
account_deactivated	Your account has been deactivated by an administrator	Contact your Nexus administrator to restore access
access_denied	You declined the Google permission screen	Click “Sign in with Google” and accept the permissions
db_error	Platform database error — contact your administrator	Wait and retry; if persistent, contact admin

Logging Out

Click "Logout" in the hub dashboard. Your session token is deleted from the browser immediately. You are returned to the login screen. No data is transmitted to the server on logout.

After logging in, you see the Hub Dashboard with these areas:

Top Bar

Main Area (Left)

Right Sidebar

Each card represents one organisation you have access to. Cards show:

• Organisation name and initials icon
• Domain — business area (e.g., "Freelance CRM", "Security Operations")
• Description — brief org purpose
• Your role — admin, user, or viewer (shown as badge)
• Status — active, pilot, or planned (colour-coded badge)
• Stats — pipeline count, runs in last 24 hours, time of last run
• Health dot — coloured indicator showing the production environment state (see below)
• Component pills — badges showing active Nexus components for this org's use-case

Card Health Indicator

Every card shows a coloured dot next to the org name indicating the live health of the production environment:

The health state refreshes every 10 seconds. Clicking the dot opens the environment health detail on the App Management page.

Entering a Workspace

1. Click any org card — you are taken to the App Management page for that org
2. Review environments, pipeline versions, and settings
3. Click the Open App button at the top of the App Management page
4. The system authenticates you within that organisation
5. The workspace loads with its custom theme and navigation
6. You are placed into the first available view automatically

The hub offers 6 visual themes:

How to Change

1. Look for the colour circles in the hub top bar
2. Click any circle to apply that theme instantly
3. The active theme shows a highlighted ring

1. Find the language button in the top bar (shows "PL" or "EN")
2. Click to toggle to the other language
3. All interface labels update immediately

Language preference is saved and restored on next visit.

After clicking an org card, you enter the workspace view with:

Sidebar (Left)

The sidebar shows navigation items specific to this organisation. Items are grouped into sections (main views, actions, pipelines) separated by thin lines.

1. Click any sidebar item to load its view
2. The active item is highlighted with the org accent colour
3. Some items show badge counts (e.g., unread items)
4. Greyed-out items are not yet available

Content Area (Centre)

Displays the result of pipeline execution. Views come in three types:

Profile Footer

At the bottom of the sidebar you see your avatar initials, display name, role, and team. Click logout to exit the workspace.

1. Navigate to a form view via the sidebar
2. The form appears with labelled input fields (text, numbers, dropdowns, dates, etc.)
3. Fill in the required information
4. Click the Submit button
5. The pipeline processes your input and shows the result

A circular button marked "N" appears in the bottom-right corner of both hub and workspace views.

1. Click the "N" button to open the action menu
2. Choose an action:

1. Open the run log via FAB → "Run Logs"
2. A panel slides in from the right showing recent pipeline runs
3. Each entry shows: pipeline name, status (success/error), duration
4. Click an entry to expand and see individual node execution details
5. Close the panel by clicking the FAB "Run Logs" again or clicking outside

Some pipelines pause at gate nodes and require your approval or input before continuing.

1. When a pipeline reaches a gate, a special approval view appears instead of normal results
2. Review the information presented (what the pipeline has done so far)
3. Choose your action: Approve, Reject, or Request Revision
4. The pipeline continues (or stops) based on your decision

The App Management page is the gateway between the hub and a live workspace. It opens when you click an org card and shows all environments, pipeline versions, and configuration for that app.

Opening the Page

1. Click any org card on the hub dashboard
2. The App Management page loads at APP_MGMT.html?org=SLUG
3. The active hub skin is inherited automatically

Page Layout

• Header — org name, environment selector, live health dot, and the Open App button
• Environments panel — list of all environments (production, staging, etc.) with status and version
• Pipeline versions — version history and diff comparison
• Settings tab — org metadata, API keys, and the RMB menu editor

Entering the Workspace

1. Click the Open App button at the top of the page
2. The system authenticates you and loads the workspace for the selected environment
3. To deep-link directly to staging: use APP_MGMT.html?org=SLUG&env=staging

Environment Actions

Each environment row shows action buttons appropriate to its current status:

Returning to Hub

1. Click Back to Hub on the App Management page, or
2. Use the FAB → Hub from within a workspace to go back all the way to the hub

Right-clicking any org card opens a context menu positioned at your cursor. It provides the most common actions for that app in one click.

Default Menu Items

Below a separator, the menu may show additional custom items configured by your administrator for that specific app (see Section 12 → Settings tab → RMB Menu Editor).

Environment Action Items

Custom items of type env_action (e.g., "Restart Staging") show an inline confirmation mini-dialog before executing. Read the impact statement and confirm or cancel.

Demo Items

Items tagged DEMO run a guided walkthrough without making any live backend calls. Safe to trigger in any environment.

Dismissing the Menu

• Click any menu item to execute it (menu closes automatically)
• Click anywhere outside the menu
• Press Escape

How roles are assigned

Nexus uses two role tiers:

• Platform role (nexus_role) — controls nav access and platform management. Set in _tbl_nexus_platform_users. Overrideable via NEXUS_ADMIN_EMAILS env var on the engine.
• Org role (org_user.role) — controls access within a specific application workspace (owner / admin / editor / viewer).

Static admin escalation (NEXUS_ADMIN_EMAILS)

The system administrator can designate permanent platform admins by setting the NEXUS_ADMIN_EMAILS environment variable on the engine (ECS task definition). Any email address on that list is automatically elevated to nexus_admin on every login, regardless of what is stored in the database. This is the primary mechanism for bootstrapping admin access.

What nexus_admin can do (current build)

• See all navigation groups: Strategy, Architecture, Use Cases, Platform, Documentation
• Access all platform documentation
• View and manage all registered platform users via the Users tab in App Management
• Switch the RBAC view to see what different roles see (planned — REQ-HUB-003)

Zarządzanie użytkownikami (REQ-AUTH-005)

The Użytkownicy tab in the App Management screen (APP_MGMT.html) is visible only to nexus_admin. It allows platform-level user management without accessing the engine directly.

Viewing the users list

1. Open any org workspace: click a hub card or navigate to APP_MGMT.html?org=SLUG
2. Click the Użytkownicy tab (visible only when you are signed in as nexus_admin)
3. The table loads all registered users: Email / Imię, Rola badge, Status dot, Ostatnie logowanie, Dołączył, Akcje
4. Your own row is highlighted and action buttons are greyed out (self-protection guard)

Changing a user’s role

1. In the user’s row click Rola
2. The role-change modal opens showing the user’s email and display name
3. Click the target role card: nexus_admin (full access) or nexus_user (Documentation only)
4. If escalating to nexus_admin an amber warning appears — confirm the action is intentional
5. Click Zmień rolę. The table refreshes with the updated role badge
6. You cannot change your own role (own row button is disabled)

Deactivating / reactivating an account

1. In the user’s row click Dezakt. (active user) or Aktywuj (deactivated user)
2. A confirmation dialog appears — click OK to proceed
3. Deactivated accounts show a grey dot and strikethrough email. The user cannot log in until reactivated
4. The account data is preserved — deactivation is reversible at any time
5. You cannot deactivate your own account (own row button is disabled)