# Portal experience

> Historical design requirements: consult [chapter 30](30-current-architecture.md) for the current implementation and outstanding work.

## Observed UIC Connect reference

The existing demo portal was inspected in the signed-in browser on 23 September 2026: Home, Device Setup & Control, Device Status Monitor and Device Tag. Observed patterns include a dark navy left sidebar, UIC Connect branding, cyan/turquoise/blue accents, white top bar, pale workspace, breadcrumbs, search panels, paginated tables, and a top-right account menu.

Home presents transaction and device-management tiles. Setup & Control filters by Cloud MID, device serial/type and payment processor; its table leads with merchant identity. Status Monitor separates heartbeat time and device timestamp and includes payment-app version and IP information. Tags exposes an intersection-selection control. These are UI observations, not evidence of backend implementation or successful device operations. No live data was changed.

## Adaptation for banks

Retain UIC visual continuity and familiar Device Management and Upgrade Manager language. Replace the merchant-first working context with a clearly visible bank/customer selector and fleet overview. Customer creation and device assignment appear only in the platform workspace. A customer administrator's Add Device action must not imply access to unassigned platform inventory.

Proposed design tokens: navy navigation `#192235`, blue primary `#315DAD`, teal highlight `#21B9C5`, pale workspace `#F3F6FB`, white surfaces and dark text `#17243B`. These are design approximations from visual inspection, not extracted official brand values. Use accessible contrast; reserve light turquoise for accents rather than small white text. Typography uses the installed system sans-serif stack.

## Information architecture

| Workspace | Navigation | Primary purpose |
| --- | --- | --- |
| Platform | Overview, Customers, Global Inventory, Assignments, Platform Audit, Settings | SuperAdmin lifecycle and governance |
| Customer | Overview | Health, offline devices, drift, recent failed operations |
| Customer | Device Management: Devices, Groups, Tags, Map | Fleet browse and organization |
| Customer | Operations: Jobs, Remote Sessions | Durable commands and support sessions |
| Customer | Upgrade Manager: Applications, Versions, Deployments | APK/ZIP catalogue and rollouts |
| Customer | Parameters: Schemas, Catalogs, Templates | Schema design and reusable configuration |
| Customer | Merchants & Sites | Optional device placement records |
| Customer | Administration: Users & Roles, Audit, Settings | Bank-scoped administration |

Explicit customer context is shown in the page header and included in routes such as `/customers/{customerId}/devices/{deviceId}`. Authorized users can switch customers, but a page already open retains its original context; changing another tab cannot redirect its mutations.

## Screen specifications

### Fleet overview

Cards show assigned devices, online/stale/offline, blocked/pending-block, configuration drift and deployment failures. Every count is filtered by the current customer and shows freshness. Click a card to open the corresponding fleet filter. Show scheduled work and recent exceptions, with no transaction-revenue emphasis.

### Device list

Primary columns: serial/device ID, model/platform, group path, merchant/site (optional), connection and last seen, reported app version, configuration status, desired/reported block state and tags. Server-side filter/search/sort/paging. Filters support descendants of a group and tags matching Any or All, continuing the current tag intersection concept.

Selection must distinguish Selected on this page from All matching results. Before a bulk operation, server resolves and freezes the target set and exclusions, shows count, customer, compatibility, schedule and expiry, and returns a preview token/hash. Execution verifies that preview and current assignment epochs. New devices matching a filter later do not join an existing deployment silently.

### Device detail

Header shows customer, serial/model, connection freshness, group path and supported operations. Tabs: Overview, Telemetry, Properties, Location, Software & Apps, Parameters, Operations, Audit. The location tab shows source, accuracy and age. Software distinguishes reported installed inventory from desired releases. Unsupported controls are disabled with a reason, not hidden without explanation.

### Groups and tags

Two-pane group tree and device list. Move a subgroup with explicit descendant impact preview and cycle validation. A non-empty group must be emptied/reparented before deletion; no silent cascade of devices. Tags have unique customer-local names, edit/merge workflows and Any/All filtering. Renaming a tag does not change frozen historical deployment selections.

### Application catalogue and deployments

Application detail separates logical app, uploaded versions, validation results, approvals and deployments. Clearly display Android APK versus Linux ZIP and compatibility. Deployment wizard: Select release → Select targets → Review exclusions → Schedule/canary → Confirm. Progress table shows each device's download/install/result and retry eligibility.

### Schema and parameter editor

Three-pane workspace: structure tree, form canvas/live preview, field properties. Header shows application, customer and version. Validation tray lists errors and impact. Device parameter forms use the same renderer, including nested records, reference pickers and masked secret fields. Save Draft, Publish Revision and Push are distinct actions.

### Remote-control session

Admission screen shows customer/device, reason, permitted mode, operator and session duration. Viewer shows connection quality, capability, elapsed/remaining time and Stop. Display a conspicuous active-control indicator; require permission for input control separately from viewing. Screen traffic is not recorded by default. Connection loss shows disconnected state and does not automatically transfer control to a different operator.

## Interaction and accessibility rules

Use semantic forms, persistent labels, keyboard focus, visible validation summaries and text alongside status colors. Provide keyboard alternatives for drag/reorder actions. Target WCAG 2.2 AA during implementation validation. Desktop is the primary authoring surface; at narrow widths the sidebar collapses and the schema editor becomes sequential panels. Tables may scroll within their container without forcing the whole page to scroll sideways.

Localize dates/numbers and display timezone. Preserve serials, identifiers and parameter keys verbatim. Proposed languages are English and Spanish. Empty states explain the next permitted action; failures preserve entered work. Saving a draft is not advertised as device success. Long jobs survive browser closure and can be resumed from Operations.

## Visual concept in the HTML guide

The HTML guide includes an illustrative bank fleet view and a schema designer sketch using fictitious devices and counts. These are design artifacts, not screenshots of a working TMS. The guide's navigation/search/print controls are functional documentation features; mock portal buttons are intentionally non-operational.