Skip to main content
Version: Next

Global UI Design

Document Type: Domain Design (Tier 2) Domain: GLOBALUI, UI, KEYBOARD Domain Character: Thin orchestration SRS References: globalui.md, ui.md, keyboard.md Status: Draft Last Updated: 2026-01-25

1. Overview​

1.1 Purpose​

The Global UI subsystem provides cross-cutting user interface behaviors that apply throughout the application. This includes system status communication, session management, user identification, notification delivery, user preference controls, display optimization, and keyboard shortcuts.

This is a thin orchestration domain. The subsystem coordinates frontend components with minimal owned business logic. Most requirements are implemented entirely in Vue.js frontend components, with backend support for:

  • Maintenance mode display (Laravel maintenance framework)
  • Feature flags (infinite scrolling toggle)
  • Session management (Cognito authentication)

1.2 Requirements Covered​

REQ IDTitlePriority
REQ-GLOBALUI-001Display Maintenance StatusMust
REQ-GLOBALUI-002Display Application VersionMust
REQ-GLOBALUI-003Communicate Session Termination ReasonMust
REQ-GLOBALUI-004Provide Idle Timeout WarningMust
REQ-GLOBALUI-005Paginate Application NotificationsMust
REQ-GLOBALUI-006Display User Display NamesMust
REQ-GLOBALUI-007Filter Sites by Cognito GroupMust
REQ-GLOBALUI-008Display User Role IndicatorMust
REQ-GLOBALUI-009Provide Infinite Scrolling ToggleMust
REQ-UI-001Display OptimizationMust
REQ-KEYBOARD-001Execute Actions via Keyboard ShortcutsMust
REQ-KEYBOARD-002Dismiss Active Modal or WidgetMust

1.3 Constraints​

Tier 2 Constraint: This document describes ownership, patterns, and design rationale. It links to reference docs for full schemas and API specifications.

1.4 Dependencies​

DirectionDomain/ComponentPurpose
ConsumesAuth/CognitoUser identity, role, session state
ClientConfigurationIdle timeout, display settings
Feature FlagsInfinite scrolling toggle state
Pusher EventsReal-time notification updates
Provides toAll Application ScreensLayout, navigation, shortcuts, modals

2. Component Architecture​

2.1 Component Diagram​

2.2 Component Responsibilities​

ComponentLayerResponsibilityREQ Trace
SpaControllerBackendServes Vue.js SPA shellAll GLOBALUI, UI, KEYBOARD
MaintenanceViewControllerBackendReturns maintenance page during deploymentREQ-GLOBALUI-001
FeaturesControllerBackendManages feature toggle stateREQ-GLOBALUI-009
FeatureBackend ModelStores feature flag stateREQ-GLOBALUI-009
AppLayout.vueFrontendMain application layout with header, sidebar, notificationsREQ-GLOBALUI-002 to 009
AppSidebar.vueFrontendNavigation sidebar with version displayREQ-GLOBALUI-002
UserRoleIndicator.vueFrontendColored role badge with tooltipREQ-GLOBALUI-008
Notifications.vueFrontendNotification bell and paginationREQ-GLOBALUI-005
CountdownDialog.vueFrontendIdle timeout warning with countdownREQ-GLOBALUI-004
PaginationToggle.vueFrontendInfinite scrolling toggle buttonREQ-GLOBALUI-009
ModalDialog.vueFrontendModal with Escape key dismissREQ-KEYBOARD-002
v-hotkeyFrontend DirectiveKeyboard shortcut bindingREQ-KEYBOARD-001, 002

3. Data Design​

3.1 Entities​

This domain does not own persistent entities. It consumes read-only data from AUTH, CLIENTCFG, and FEATURES.

EntityOwnerUsage in GLOBALUI
usersAUTHRole, display_name, logged_in_site, visible_sites
featuresFEATURESFeature toggle states
client_configurationsCLIENTCFGIdle timeout duration
sitesSITESite filtering by Cognito group

See Database Reference for full schema.

3.2 Data Structures​

User Role Indicator Mapping (Frontend)

interface RoleIndicatorDetails {
  roleIndicator: string;     // 'SA', 'J', 'S', 'CA', 'M'
  circleBackgroundColor: string;  // Hex color code
  toolTip: string;           // Tooltip text
}

const roleIndicatorDetailsMap: Record<UserRole, RoleIndicatorDetails> = {
  SUPER_ADMIN: { roleIndicator: 'SA', circleBackgroundColor: '#000000', toolTip: 'Super Admin user' },
  JUNIOR: { roleIndicator: 'J', circleBackgroundColor: '#B7B0FF', toolTip: 'Junior user' },
  SENIOR: { roleIndicator: 'S', circleBackgroundColor: '#49D1A0', toolTip: 'Senior user' },
  CLIENT_ADMIN: { roleIndicator: 'CA', circleBackgroundColor: '#FAA07A', toolTip: 'Client Admin user' },
  MANAGER: { roleIndicator: 'M', circleBackgroundColor: '#FF3A8D', toolTip: 'Manager user' },
};

Notification Pagination (API Response)

interface PaginatedNotifications {
  data: Notification[];
  total: number;
  to: number;
  skip: number;
  take: number;
}

interface NotificationParams {
  skip: number;  // Offset for pagination
  take: number;  // Number to fetch (10, 20, 30, 50)
}

Keyboard Shortcut Binding

interface HotkeyBinding {
  [key: string]: {
    keyup?: () => void;
    keydown?: () => void;
  };
}

// Example: Modal Escape key binding
const hotkeyBinding: HotkeyBinding = {
  escape: {
    keyup: () => closeModal()
  }
};

3.3 State Transitions​

This domain is stateless. All operations are request-scoped.

Exception: Idle timeout tracking is managed in-memory by the IdleJs library.

4. Interface Design​

4.1 APIs Consumed​

EndpointMethodPurposeResponse Fields Used
/GETSPA entry pointHTML shell
/api/featuresGETFetch feature flags{ code: { is_enabled } }
/api/features/:idPATCHToggle feature{ is_enabled: boolean }
/api/paginate-notificationsGETPaginated notifications{ data, total, to }
/api/unread-notificationsGETUnread count{ unread: number }
/api/client-configuration-settingsGETClient config{ idle_timeout, ... }

4.2 APIs Provided​

This domain does not provide APIs to other domains. It serves frontend components and consumes existing APIs.

4.3 Events​

EventDirectionPayloadPurpose
NotificationReadPusher → Frontend{}Refresh notification list
OtherDeviceLogoutPusher → Frontend{}Force page reload
UserAccountDeletedPusher → Frontend{}Force logout with message
UserAccountDisabledPusher → Frontend{}Force logout with message
feature-toggledEventBus{}Sync feature flags

5. Behavioral Design​

5.1 Idle Timeout Warning Flow​

5.2 Site Filtering by Cognito Group​

Algorithm: Filter Visible Sites

Inputs:
- user: User - The authenticated user
- all_sites: Site[] - All sites in the system

Outputs:
- visible_sites: Site[] - Sites the user can access

Steps:
1. If user.cognito_group IS NOT NULL:
   Return all_sites (user sees everything)
2. Else:
   Return all_sites WHERE site.requires_cognito_group = false

Notes:
- Cognito group presence grants universal site access
- Sites can be marked as requiring Cognito group for visibility

Decision Logic

User Has Cognito GroupSite Requires CognitoSite Visible
YesYesYes
YesNoYes
NoYesNo
NoNoYes

Precedence: User group checked first; site requirement checked only for users without group. Default: If no match, site is hidden.

5.3 Keyboard Shortcut Resolution​

Algorithm: Resolve Keyboard Shortcut

Inputs:
- key_event: KeyboardEvent - The key press event
- active_element: Element - Currently focused DOM element
- bound_shortcuts: Map<string, Action> - Registered shortcuts

Outputs:
- executed: boolean - Whether an action was triggered

Steps:
1. If active_element is text input (input, textarea, contenteditable):
   Return false (pass key to text input)
2. If key_event.key NOT IN bound_shortcuts:
   Return false (ignore unbound key)
3. If modal or widget is already open AND key != 'Escape':
   Return false (block additional modals)
4. Execute bound_shortcuts[key_event.key]
5. Return true

Notes:
- Escape key always works, even with modal open (closes it)
- Single-letter shortcuts (no modifier) for efficiency
- v-hotkey directive handles binding lifecycle

5.4 Notification Pagination​

6. Error Handling​

ConditionDetectionResponseUser Impact
Maintenance mode activeLaravel middlewareRedirect to maintenance pageCannot access application
Session expired401 responseRedirect to login with messageMust re-authenticate
Idle timeoutIdleJs callbackShow countdown, then logoutWarning before logout
Account deleted/disabledPusher eventForce logout with messageImmediate termination
Feature API timeoutNetwork errorUse cached stateStale feature flags

7. Configuration​

SettingLocationDefaultEffect
idle_timeoutclient_configurations30 (minutes)Time before idle warning
show_evaluation_warningclient_configurationsfalseDisplay pre-production warning
paginator_per_pageuser.settings20 or 'All'Infinite scroll on/off
sidebar_pinneduser.settingstrueSidebar collapse behavior
color_schemeuser.settings'system'Light/dark mode

See Configuration Reference for details.

8. Implementation Mapping​

8.1 Code Locations​

ComponentTypePath
SpaControllerControllercode/app/Http/Controllers/SpaController.php
MaintenanceViewControllerControllercode/app/Http/Controllers/MaintenanceViewController.php
FeaturesControllerControllercode/app/Http/Controllers/FeaturesController.php
FeatureModelcode/app/Feature.php
AppLayoutLayoutcode/resources/frontend/src/layouts/AppLayout.vue
AppSidebarComponentcode/resources/frontend/src/components/AppSidebar.vue
UserRoleIndicatorComponentcode/resources/frontend/src/components/users/UserRoleIndicator.vue
NotificationsComponentcode/resources/frontend/src/components/app-notifications/Notifications.vue
CountdownDialogComponentcode/resources/frontend/src/components/CountdownDialog.vue
ModalDialogComponentcode/resources/frontend/src/components/ModalDialog.vue
PaginationToggleComponentcode/resources/frontend/src/components/common/PaginationToggle.vue
SettingsViewcode/resources/frontend/src/views/Settings.vue
v-hotkeyPlugincode/resources/frontend/src/plugins/index.js

8.2 Requirement Traceability​

REQ IDDesign SectionCode Location
REQ-GLOBALUI-001§5 (maintenance flow)MaintenanceViewController.php
REQ-GLOBALUI-002§2.2AppSidebar.vue (appVersion computed)
REQ-GLOBALUI-003§5.1AppLayout.vue (logout message), logout.ts
REQ-GLOBALUI-004§5.1AppLayout.vue (IdleJs), CountdownDialog.vue
REQ-GLOBALUI-005§5.4Notifications.vue, NotificationPane.vue
REQ-GLOBALUI-006§2.2AppLayout.vue (user.display_name)
REQ-GLOBALUI-007§5.2AppLayout.vue (visibleSites), Site queries
REQ-GLOBALUI-008§3.2UserRoleIndicator.vue
REQ-GLOBALUI-009§2.2PaginationToggle.vue, FeaturesController.php
REQ-UI-001§2Responsive CSS in all Vue components
REQ-KEYBOARD-001§5.3v-hotkey directive usage across views
REQ-KEYBOARD-002§5.3ModalDialog.vue, CountdownDialog.vue (escape binding)

9. Design Decisions​

DecisionRationaleAlternatives Considered
Frontend-heavy implementationMost requirements are UI concerns; keeps backend minimalBackend rendering (rejected: slower, less interactive)
IdleJs library for idle detectionWell-tested, configurable, handles edge casesCustom implementation (rejected: reinventing wheel)
v-hotkey directive for shortcutsDeclarative binding, component lifecycle managementGlobal event listener (rejected: harder to manage)
Single-letter shortcutsEfficiency for power users, industry standardModifier keys (rejected: slower, but available as fallback)
Role indicator in headerAlways visible, consistent locationProfile menu only (rejected: less discoverable)
Infinite scroll as user preferenceDifferent users have different workflowsSystem-wide setting (rejected: inflexible)
DocumentRelevant Sections
SRS: globalui.mdGLOBALUI requirements source
SRS: ui.mdUI requirements source
SRS: keyboard.mdKEYBOARD requirements source
SDS: ArchitectureSPA architecture, Vue.js patterns
SDS: SecurityCognito authentication, session management
SDS: NOTIF DomainNotification indicator subsystem
SDS: USERMGMT DomainUser role management