````md # Acquiring Platform — Navigation Architecture & UI Requirements **Document ID:** UI-NAV-001 **Document Type:** Product / UI Functional Requirements **Version:** 1.0 **Status:** Proposed **Product:** Acquiring Platform **Scope:** Platform Navigation, Module Switching and Contextual Sidebar **Audience:** Product, UX/UI, Frontend, Backend and QA Teams --- # 1. Document Purpose This document defines the navigation architecture and user interface requirements for the Acquiring Platform. The platform contains a large number of functional areas including: - Merchant Management - Terminal Management - Payment Processing - Clearing - Settlement - Reconciliation - Disputes & Chargebacks - Risk & Fraud - Scheme Management - Security & Key Management - Administration - AI-assisted operations The existing navigation approach exposes a very large number of menu items in a single vertical sidebar. This makes the platform difficult to navigate and causes unrelated functions to appear together. The proposed design introduces a **two-level navigation model**: 1. **Top Module Dock** — selects the major business domain. 2. **Contextual Left Navigation** — displays only the functions relevant to the selected domain. 3. ** Add Colors** The navigation should provide an enterprise-grade experience while taking visual inspiration from the **macOS Dock** for module switching. --- # 2. Design Objective The primary objective is: > **Select the business domain first, then display only the functions relevant to that domain.** Instead of: ```text 100+ functions | v One very long sidebar ```` the proposed navigation should work as: ```text Major Business Domains | v Select Module | v Contextual Left Navigation | v Business Function | v Page / Operation ``` This should significantly reduce visual complexity while still allowing the platform to support a large number of functions. --- # 3. Navigation Architecture The overall navigation hierarchy shall be: ```text ACQUIRING PLATFORM │ ├── Top Module Dock │ │ ├── Overview │ ├── Merchant │ ├── Terminal │ ├── Payments │ ├── Clearing & Settlement │ ├── Reconciliation │ ├── Disputes │ ├── Risk & Fraud │ ├── Schemes & Network │ ├── Security & Administration │ └── AI Agent │ └── Contextual Left Navigation │ ├── Menu Group │ ├── Function │ ├── Function │ └── Function │ ├── Menu Group │ ├── Function │ └── Function │ └── Menu Group ``` --- # 4. Top-Level Modules The initial proposed top-level modules are: | # | Module | Primary Purpose | | -- | ------------------------- | ------------------------------------------------- | | 1 | Overview | Platform-wide dashboard, analytics and alerts | | 2 | Merchant | Merchant lifecycle and configuration | | 3 | Terminal | Terminal/device lifecycle and configuration | | 4 | Payments | Transaction processing and payment operations | | 5 | Clearing & Settlement | Clearing, settlement and payout operations | | 6 | Reconciliation | Financial and transaction reconciliation | | 7 | Disputes | Chargebacks and dispute management | | 8 | Risk & Fraud | Risk controls, fraud monitoring and investigation | | 9 | Schemes & Network | Card schemes, network and scheme parameters | | 10 | Security & Administration | HSM, keys, users, roles, security and audit | | 11 | AI Agent | AI-assisted operational intelligence | The final list may be extended as additional platform domains are finalized. --- # 5. Top Module Dock ## 5.1 Concept The Top Module Dock is the primary mechanism for switching between major platform modules. The visual concept should be inspired by the **macOS Dock** rather than a conventional navigation bar. The dock should feel like a: > **Business Module Launcher** rather than a traditional menu. --- # 6. Top Dock Layout The dock should visually resemble: ```text ┌──────────────────────────────────────────────────────────────────────────┐ │ │ │ Overview Merchant Terminal Payments Clearing Recon Dispute │ │ 🏠 👥 🖥 ▣ ◫ ⇄ ⚖ │ │ │ │ ▲ │ │ ACTIVE │ │ │ └──────────────────────────────────────────────────────────────────────────┘ ``` The actual implementation should use the application's visual identity and icon library. --- # 7. Top Dock Module Items Each module should contain: * Module icon * Module name * Active state * Hover state * Optional tooltip * Optional short description where appropriate Example: ```text ┌───────────────┐ │ 🖥 │ │ Terminal │ └───────────────┘ ``` The selected module should be visually elevated compared with the other modules. --- # 8. MacOS Dock Style Interaction The Top Dock should visually behave similar to a desktop dock. ## 8.1 Normal State Non-selected modules should have: * Standard icon size * Normal text weight * Low visual emphasis * Consistent spacing ## 8.2 Hover State When the user moves the pointer over a module: * The module icon should increase in size. * The module container may increase slightly. * The label should become more prominent. * Adjacent modules may move slightly. * The transition should be smooth. Example: ```text Normal: [ Merchant ] [ Terminal ] [ Payments ] Hover: [ Merchant ] [ TERMINAL ] [ Payments ] ↑ Magnified ``` --- # 9. Active Module State There shall always be one active module. Example: ```text Overview Merchant Terminal ← ACTIVE Payments Clearing Disputes Risk & Fraud Schemes Security AI Agent ``` The active module should have: * Highlighted background * Larger or emphasized icon * Stronger label * Active indicator * Optional glow/shadow * Smooth transition The active state must be visually obvious even without relying on color alone. --- # 10. Gesture-Based Module Switching The Top Dock should support gesture-based navigation. Supported interactions should include, where technically available: * Trackpad horizontal swipe * Mouse wheel / horizontal scroll * Touch swipe * Drag gesture * Click/tap on module * Keyboard navigation The gesture interaction should allow the user to move through the module sequence. Example: ```text Swipe / Scroll Left ↓ Previous Module Swipe / Scroll Right ↓ Next Module ``` --- # 11. Gesture Navigation Behavior The module sequence should be deterministic. Example: ```text Overview ↓ Merchant ↓ Terminal ↓ Payments ↓ Clearing & Settlement ↓ Reconciliation ↓ Disputes ↓ Risk & Fraud ↓ Schemes & Network ↓ Security & Administration ↓ AI Agent ``` Scrolling right should move forward. Scrolling left should move backward. The current module should remain centered or visually emphasized when possible. --- # 12. Dock Overflow The platform may eventually have more modules than can comfortably fit on the screen. The dock must therefore support overflow. Possible behavior: ```text < Overview Merchant Terminal Payments Clearing ... > ``` The user can: * Scroll through modules. * Use left/right navigation controls. * Use trackpad gesture. * Select a module directly. The implementation should avoid shrinking module icons/text to an unusable size simply to fit all modules. --- # 13. Dock Animation Animations should be smooth and subtle. Recommended behavior: | Interaction | Recommended Duration | | ------------------- | -------------------: | | Hover magnification | 150–250 ms | | Module selection | 200–300 ms | | Module transition | 200–300 ms | | Sidebar transition | 200–300 ms | | Menu expansion | 150–250 ms | Animations should not interfere with operational activities. --- # 14. Critical Navigation Rule ## Contextual Left Navigation The left navigation **MUST only display menus belonging to the currently selected top-level module.** This is one of the most important requirements in this document. For example: ```text Selected Module = Terminal ``` The sidebar should contain: ```text Terminal ├── Terminals ├── Configuration ├── OTA Updates └── Certification ``` It must NOT simultaneously display: ```text Settlement Disputes Risk Scheme Management HSM User Management ``` This is intended to prevent the sidebar from becoming excessively long. --- # 15. Contextual Sidebar Behavior When the top module changes: ```text Top Dock | v Selected Module Changes | v Sidebar Menu Changes | v Default Page / Current Page Changes ``` Example: ```text Before: Top Module = Terminal Sidebar: Terminals Configuration OTA Certification After: Top Module = Payments Sidebar: Transactions Payment Channels Routing Monitoring ``` --- # 16. Sidebar Structure Each module's sidebar should contain logical menu groups. Recommended structure: ```text MODULE NAME GROUP 1 Function Function Function GROUP 2 Function Function GROUP 3 Function Function ``` Menu groups should be visually separated using: * Group heading * Spacing * Optional divider * Consistent typography --- # 17. Sidebar Menu Group Behavior Menu groups should support: * Expand * Collapse * Active state * Scroll * Hover state * Keyboard navigation Example: ```text CONFIGURATION ▲ Parameter Dashboard Device Config Templates Push Logs Config Versions Version Compliance ``` Collapsed: ```text CONFIGURATION ▼ ``` --- # 18. Sidebar Scroll If the selected module contains many functions, the sidebar should scroll independently from the main content area. Example: ```text ┌──────────────┬─────────────────────────────────────────┐ │ │ │ │ SIDEBAR │ MAIN CONTENT │ │ │ │ │ ↕ │ ↕ │ │ sidebar │ page scrolling │ │ scrolling │ │ │ │ │ └──────────────┴─────────────────────────────────────────┘ ``` The sidebar should not force the entire application page to scroll horizontally. --- # 19. Sidebar Collapse The sidebar should support: ### Expanded ```text ┌─────────────────────────┐ │ TERMINAL │ │ │ │ TERMINALS │ │ All Terminals │ │ Locations │ │ Groups │ │ TID / Identity │ │ │ │ CONFIGURATION │ │ Parameter Dashboard │ │ Device Config │ │ Templates │ └─────────────────────────┘ ``` ### Collapsed ```text ┌──────┐ │ 🖥 │ │ 📍 │ │ ▦ │ │ ⚙ │ │ 🔧 │ └──────┘ ``` When collapsed: * Icons remain visible. * Tooltips should identify the function. * Active item must remain visually identifiable. --- # 20. Module 01 — Overview ## Purpose Provide a high-level view of the entire acquiring platform. ### Dashboard ```text OVERVIEW DASHBOARD Overview ANALYTICS Analytics MONITORING Alerts ``` Future additions may include: * Transaction Overview * Operational Overview * Financial Overview * Platform Health * Executive Dashboard --- # 21. Module 02 — Merchant ## Purpose Manage merchant lifecycle, hierarchy, configuration and commercial information. ```text MERCHANT MERCHANT MANAGEMENT Merchant Dashboard Merchant Search Merchant Onboarding Merchant Profile Merchant Hierarchy Merchant Groups Merchant Status MERCHANT CONFIGURATION Merchant Accounts MID Management Merchant Locations MCC Payment Products Acquiring Configuration COMMERCIAL MDR / Pricing Fees Fee Overrides Merchant Contracts ``` The final Merchant menu should be refined after the complete Merchant Management and MDR menu inventory is available. --- # 22. Module 03 — Terminal ## Purpose Manage terminals, device configuration, OTA updates and certification. ```text TERMINAL TERMINALS All Terminals Locations Groups TID / Identity CONFIGURATION Parameter Dashboard Device Config Templates Push Logs Config Versions Version Compliance OTA UPDATES App Packages Update Jobs Update Status CERTIFICATION Terminal Certifications ``` --- # 23. Terminal — Menu Mapping from Existing UI The existing menus should map as follows: | Existing Menu | New Location | | ----------------------- | ------------------------- | | All Terminals | Terminal → Terminals | | Locations | Terminal → Terminals | | Groups | Terminal → Terminals | | TID Master | Terminal → TID / Identity | | Parameter Dashboard | Terminal → Configuration | | Templates | Terminal → Configuration | | Push Logs | Terminal → Configuration | | Device Config | Terminal → Configuration | | Config Versions | Terminal → Configuration | | Version Compliance | Terminal → Configuration | | App Packages | Terminal → OTA Updates | | Update Jobs | Terminal → OTA Updates | | Update Status | Terminal → OTA Updates | | Terminal Certifications | Terminal → Certification | --- # 24. Module 04 — Payments ## Purpose Manage payment transactions, payment channels, routing and transaction monitoring. ```text PAYMENTS TRANSACTIONS Transaction Dashboard All Transactions Transaction Search Transaction Details Refunds Reversals Voids PAYMENT CHANNELS POS QR E-Commerce Contactless Wallets ROUTING Network Routing Payment Routing Rules Acquirer Routing Fallback Rules MONITORING Transaction Monitoring Failed Transactions Declined Transactions Transaction Alerts ``` --- # 25. Module 05 — Clearing & Settlement ## Purpose Manage clearing, settlement, payout and financial operations. ```text CLEARING & SETTLEMENT CLEARING Clearing Dashboard Clearing Batches Clearing Files Clearing Exceptions SETTLEMENT Settlement Dashboard POS Settlements QR Settlements Settlement Transactions Payouts FINANCIAL OPERATIONS Adjustments Risk Holds MIS / Reports Settlement Approvals CALENDAR Settlement Calendar Holiday Calendar ``` --- # 26. Settlement Menu Mapping | Existing Menu | New Location | | ------------------- | -------------------------------------------- | | POS Settlements | Clearing & Settlement → Settlement | | QR Settlements | Clearing & Settlement → Settlement | | All Transactions | Payments | | MIS Approval | Clearing & Settlement → Financial Operations | | Adjustments | Clearing & Settlement → Financial Operations | | Payouts | Clearing & Settlement → Settlement | | Risk Holds | Risk & Fraud | | Settlement Calendar | Clearing & Settlement → Calendar | | Holiday Calendar | Clearing & Settlement → Calendar | --- # 27. Module 06 — Reconciliation ## Purpose Manage reconciliation across transaction, clearing, settlement and network sources. ```text RECONCILIATION RECONCILIATION Reconciliation Dashboard Transaction Reconciliation Settlement Reconciliation Clearing Reconciliation Network Reconciliation EXCEPTIONS Recon Exceptions Unmatched Transactions Missing Transactions Duplicate Transactions Amount Mismatches FILES File Tracker File Processing File History Processing Errors ``` --- # 28. Module 07 — Disputes ## Purpose Manage chargebacks, disputes, workflow, SLA and dispute analytics. ```text DISPUTES CASE MANAGEMENT Dispute Dashboard Chargeback Cases Dispute Cases Case Search Case Details WORKFLOW Queues Workflow Configuration Approval Queue RULES & SLA Reason Codes & SLA Dispute Parameters Automation Rules ANALYTICS Win Rate Analytics Dispute Analytics Recovery Analytics ``` --- # 29. Dispute Menu Mapping | Existing Menu | New Location | | ---------------------- | -------------------------- | | Chargeback Cases | Disputes → Case Management | | Win Rate Analytics | Disputes → Analytics | | Reason Codes & SLA | Disputes → Rules & SLA | | Queues | Disputes → Workflow | | Workflow Configuration | Disputes → Workflow | | Automation Rules | Disputes → Rules & SLA | | Approval Queue | Disputes → Workflow | `Card Schemes` should NOT remain under Disputes. It belongs under: ```text Schemes & Network └── Scheme Management ``` --- # 30. Module 08 — Risk & Fraud ## Purpose Manage fraud prevention, risk rules, risk controls and investigations. ```text RISK & FRAUD RISK MANAGEMENT Risk Dashboard Risk Rules Risk Policies Risk Holds Risk Alerts FRAUD MANAGEMENT Fraud Dashboard Fraud Rules Fraud Monitoring Fraud Cases Fraud Patterns INVESTIGATION Investigations Incidents Evidence Investigation Queue TESTING Test Import Rule Testing Simulation ``` --- # 31. Risk Menu Mapping | Existing Menu | New Location | | ------------------------- | ------------------------------ | | Risk Rules | Risk & Fraud → Risk Management | | Risk Management Dashboard | Risk & Fraud → Risk Management | | Test Import | Risk & Fraud → Testing | | Risk Holds | Risk & Fraud → Risk Management | --- # 32. Module 09 — Schemes & Network ## Purpose Manage card schemes, network parameters, EMV configuration, interchange, scheme fees and scheme compliance. ```text SCHEMES & NETWORK SCHEME MANAGEMENT Scheme Dashboard Schemes Countries Currencies Products & Services (per-scheme: Cards Product, Authorization, Clearing, Settlement, + network value-added programs — see below) BIN / IIN Ranges EMV & CONTACTLESS EMV AIDs CAPKs Contactless Parameters NETWORK Network Routing Network Parameters COMMERCIAL Interchange Rates Scheme Fees DISPUTE PARAMETERS Reason Codes Dispute Parameters SETTLEMENT PARAMETERS Settlement Calendar Holiday Calendar CERTIFICATION & COMPLIANCE Certifications Compliance Records SCHEME INTELLIGENCE Bulletins MCC Rules ``` ## Products & Services — per-scheme catalog "Products & Services" is a single page (not additional sidebar items) that lets the user pick a scheme, then a service within that scheme. Every scheme gets four core services; Mastercard and Visa additionally get their network-specific value-added programs. Any other scheme (present or future — `SchemeCore.Scheme.code` is free-text on purpose) falls back to the core four automatically. The catalog is declared in `SchemeCore.ServiceCatalog`. ```text Core (every scheme) Cards Product Authorization & Other Transaction Types Clearing Settlement Mastercard adds Mastercom MDES Click to Pay Identity Check Account Updater Ethoca Visa adds VTS Click to Pay Visa Secure VAU VROL Other schemes (core four only) ``` Cards Product keeps its own `SchemeCore.CardProduct` CRUD; every other service shares one generic `SchemeCore.SchemeServiceConfig` CRUD scoped to the selected scheme + service key. --- # 33. Scheme Menu Mapping from Existing UI | Existing Menu | New Location | | ---------------------- | ---------------------------------------------- | | Scheme Dashboard | Schemes & Network → Scheme Management | | Schemes | Schemes & Network → Scheme Management | | Countries | Schemes & Network → Scheme Management | | Currencies | Schemes & Network → Scheme Management | | Card Products | Schemes & Network → Scheme Management → Products & Services (per scheme, one tab among several) | | BIN / IIN Ranges | Schemes & Network → Scheme Management | | EMV AIDs | Schemes & Network → EMV & Contactless | | CAPKs | Schemes & Network → EMV & Contactless | | Contactless Parameters | Schemes & Network → EMV & Contactless | | Network Routing | Schemes & Network → Network | | Network Parameters | Schemes & Network → Network | | Interchange Rates | Schemes & Network → Commercial | | Scheme Fees | Schemes & Network → Commercial | | Reason Codes | Schemes & Network → Dispute Parameters | | Dispute Parameters | Schemes & Network → Dispute Parameters | | Settlement Calendar | Schemes & Network → Settlement Parameters | | Holiday Calendar | Schemes & Network → Settlement Parameters | | Certifications | Schemes & Network → Certification & Compliance | | Compliance Records | Schemes & Network → Certification & Compliance | | Bulletins | Schemes & Network → Scheme Intelligence | | MCC Rules | Schemes & Network → Scheme Intelligence | --- # 34. Module 10 — Security & Administration ## Purpose Manage HSM, cryptographic keys, users, roles, security and audit. ```text SECURITY & ADMINISTRATION HSM & KEY MANAGEMENT HSM Dashboard HSM Keys Key Management Key Rotation Schedules Key Ceremony Logs SECURITY Security Policies Certificates Encryption Configuration ADMINISTRATION User Management Role Management Permission Management Audit & Compliance PROFILE My Profile ``` --- # 35. Security Menu Mapping The following existing menus should be reorganized: ```text Key Rotation Schedules ↓ Security & Administration └── HSM & Key Management Key Ceremony Logs ↓ Security & Administration └── HSM & Key Management Audit & Compliance ↓ Security & Administration └── Administration User Management ↓ Security & Administration └── Administration Role Management ↓ Security & Administration └── Administration My Profile ↓ Security & Administration └── Profile ``` --- # 36. Direct Acquiring Section The existing `DIRECT ACQUIRING` section should not remain as a standalone navigation group. The current contents are: ```text Terminal Certifications Key Rotation Schedules Key Ceremony Logs ``` These belong to different business domains. They should be moved to: ```text Terminal └── Certification └── Terminal Certifications Security & Administration └── HSM & Key Management ├── Key Rotation Schedules └── Key Ceremony Logs ``` The `DIRECT ACQUIRING` navigation category should therefore be removed unless additional direct-acquiring functions are later identified. --- # 37. Module 11 — AI Agent ## Purpose AI Agent provides cross-platform operational intelligence and assistance. Unlike other modules, AI Agent should be considered a **cross-domain capability**. Suggested navigation: ```text AI AGENT OPERATIONS Incidents Investigations INTELLIGENCE AI Recommendations AI Analysis PLAYBOOK Playbook Review WORKFLOW Approval Queue HISTORY Investigation History AI Action History ``` AI Agent may be accessible both through: ```text Top Dock → AI Agent ``` and through a persistent global AI control. --- # 38. AI Agent Cross-Module Capability AI Agent should be capable of analyzing information across multiple modules. Example: ```text AI Agent | +-- Payment Investigation | | | +-- Transaction | +-- Terminal | +-- Risk | +-- Settlement | +-- Fraud Investigation | +-- Settlement Investigation | +-- Terminal Incident ``` The AI Agent should not be architecturally restricted to one module's data. --- # 39. Global Header The global header may contain: ```text ┌─────────────────────────────────────────────────────────────┐ │ Logo Module / Breadcrumb Search Alerts User │ └─────────────────────────────────────────────────────────────┘ ``` Recommended global functions: * Global Search * Notifications * Help * User Profile * Settings * Logout These should remain independent of the selected business module. --- # 40. Global Search A global search option should be considered. The search should be capable of searching across authorized platform objects. Examples: ```text Search: MID TID Merchant Transaction Chargeback Case Terminal Serial Number BIN ``` Search results should respect user permissions. --- # 41. Permission-Based Navigation Navigation visibility should be permission-aware. A user should only see: * Modules they are authorized to access. * Menu items they are authorized to access. * Functions/actions allowed by their role. Example: ```text Administrator ↓ All Modules Settlement User ↓ Clearing & Settlement Reconciliation Dispute User ↓ Disputes Terminal Operations User ↓ Terminal ``` The system should not simply hide the UI while allowing unauthorized URLs to be accessed. Authorization must also be enforced at the application/backend level. --- # 42. Module Availability The Top Dock should dynamically support modules based on: 1. User permissions. 2. Tenant configuration. 3. Product/package configuration. 4. Feature enablement. Example: ```text User A Overview Merchant Terminal Payments Settlement Disputes User B Overview Terminal Payments ``` A module that is unavailable to a user should not appear in the Top Dock. --- # 43. Deep Linking Every functional page should have a stable URL. Example: ```text /acquiring/terminal/terminals /acquiring/terminal/configuration /acquiring/payments/transactions /acquiring/settlement/dashboard /acquiring/reconciliation/exceptions /acquiring/disputes/cases /acquiring/risk/rules /acquiring/schemes/bins /acquiring/security/hsm ``` The URL should determine: * Active top module. * Active sidebar menu. * Active menu group. * Main page. --- # 44. Browser Refresh When the user refreshes a page: ```text URL ↓ Identify Module ↓ Identify Menu ↓ Restore Top Dock ↓ Restore Sidebar ↓ Load Page ``` The user should not be returned to the default dashboard unnecessarily. --- # 45. Back / Forward Navigation Browser back and forward functionality should work correctly. Example: ```text Terminal ↓ All Terminals ↓ Terminal Details ↓ Configuration ``` Browser Back should return through the user's actual navigation history. --- # 46. Active Menu State The active sidebar item must be visually distinct. Example: ```text TERMINALS ┌──────────────────────────┐ │ 🖥 All Terminals │ ← ACTIVE └──────────────────────────┘ Locations Groups TID / Identity ``` The active state should not rely exclusively on color. --- # 47. Breadcrumb The main content area should show the current navigation context. Example: ```text Terminal > Terminals > All Terminals ``` For example: ```text Schemes & Network > Scheme Management > BIN / IIN Ranges ``` This helps users understand their location within the platform. --- # 48. Responsive Design The navigation should support: * Desktop * Laptop * Large monitor * Tablet * Touch-enabled device The primary design target is enterprise desktop usage. --- # 49. Touch Navigation On touch devices: ```text Swipe Left ↓ Next Module Swipe Right ↓ Previous Module ``` The left navigation may be presented as a slide-out drawer. --- # 50. Keyboard Navigation All navigation actions must have keyboard alternatives. Suggested: ```text Tab ↓ Move between controls Arrow Left / Right ↓ Move between Top Dock modules Enter ↓ Select module Arrow Up / Down ↓ Navigate sidebar Enter ↓ Open menu ``` The exact keyboard mapping may be finalized during UX implementation. --- # 51. Accessibility The navigation must support: * Keyboard navigation. * Focus indicators. * Screen readers. * Accessible labels. * Sufficient contrast. * Non-color active states. * Accessible tooltips. * Gesture alternatives. Gestures must never be the only method of navigation. --- # 52. Visual Design Principles The overall design should follow the existing Shukria design language. Recommended characteristics: * Clean enterprise UI. * White/light main content area. * Purple/indigo primary branding. * Rounded cards. * Subtle shadows. * Consistent iconography. * Minimal visual noise. * Clear typography. * Strong active-state indication. * Professional financial-services appearance. --- # 53. Top Dock Visual Principles The Top Dock should: * Feel lightweight. * Feel elevated/floating. * Have rounded corners. * Have subtle shadow. * Provide icon magnification. * Provide clear active state. * Avoid looking like a standard Bootstrap/navbar menu. * Avoid consuming excessive vertical space. * Avoid displaying secondary functions. The Top Dock should contain **only Level-1 modules**. --- # 54. Sidebar Visual Principles The sidebar should: * Display only the selected module. * Group functions logically. * Use consistent icons. * Clearly show the active function. * Support scrolling. * Support collapse. * Avoid excessive nested levels. The sidebar should generally stop at: ```text Module ↓ Group ↓ Function ``` Deep nesting should be avoided. --- # 55. Navigation Depth Recommended maximum visible navigation hierarchy: ```text Level 1 Top Module Level 2 Menu Group Level 3 Function ``` Example: ```text Terminal ↓ Configuration ↓ Device Config ``` Avoid navigation such as: ```text Terminal ↓ Configuration ↓ Device ↓ Android ↓ Parameters ↓ Version ``` Such complexity should be handled inside the functional page rather than through the global navigation. --- # 56. Important Menu Classification Rules When adding new menus, the following rules should be applied. ### Rule 1 If the function relates primarily to a business domain, place it under that domain. ### Rule 2 If the function is used across multiple domains, consider placing it under Administration or making it globally accessible. ### Rule 3 Scheme-specific configuration should remain under: ```text Schemes & Network ``` ### Rule 4 Cryptographic key management should remain under: ```text Security & Administration ``` ### Rule 5 Terminal/device lifecycle functions should remain under: ```text Terminal ``` ### Rule 6 Transaction execution and operational payment functions should remain under: ```text Payments ``` ### Rule 7 Financial matching and exception management should remain under: ```text Reconciliation ``` ### Rule 8 Chargebacks and dispute lifecycle should remain under: ```text Disputes ``` ### Rule 9 Fraud and transaction risk controls should remain under: ```text Risk & Fraud ``` ### Rule 10 Merchant commercial configuration should remain under: ```text Merchant ``` unless it becomes a sufficiently large independent domain such as Fee/MDR Management. --- # 57. Future Fee / MDR Module If Fee and MDR Management becomes a substantial product capability, it should be considered as a separate top-level module. Potential future structure: ```text FEE & MDR FEE MANAGEMENT Fee Dashboard Fee Rules Fee Types Fee Components MDR MDR Rules MDR Profiles Merchant Pricing Scheme Pricing CONFIGURATION Fee Templates Overrides Effective Dates ANALYTICS Fee Revenue MDR Analysis Pricing Analysis ``` This should be finalized after the complete Fee/MDR menu inventory is available. --- # 58. Future Payment Switch Module If the payment switch is exposed as an operational product module, it may also become a separate top-level domain. Potential structure: ```text PAYMENT SWITCH SWITCH DASHBOARD Switch Overview Transaction Monitor ROUTING Routing Rules Route Configuration Failover NETWORK Network Connections Network Status MESSAGING ISO Messages Message Logs OPERATIONS Switch Alerts Exceptions Diagnostics ``` This should only be promoted to a Top Dock module if it represents a distinct user-facing operational domain. --- # 59. Recommended Final Module Model The initial architecture should therefore be: ```text ┌──────────────────────────────────────────────────────────────┐ │ TOP MODULE DOCK │ │ │ │ Overview | Merchant | Terminal | Payments | Clearing | ... │ └──────────────────────────────────────────────────────────────┘ │ ▼ SELECTED BUSINESS MODULE │ ▼ ┌───────────────────────┬──────────────────────────────────────┐ │ CONTEXTUAL SIDEBAR │ MAIN CONTENT │ │ │ │ │ Module │ │ │ │ │ │ GROUP │ │ │ Function │ Page / Dashboard │ │ Function │ │ │ │ │ │ GROUP │ │ │ Function │ │ │ Function │ │ │ │ │ └───────────────────────┴──────────────────────────────────────┘ ``` --- # 60. Example — Terminal User Journey The user opens the platform. ```text Top Dock ↓ Terminal selected ``` The sidebar displays: ```text TERMINAL TERMINALS All Terminals Locations Groups TID / Identity CONFIGURATION Parameter Dashboard Device Config Templates Push Logs Config Versions Version Compliance OTA UPDATES App Packages Update Jobs Update Status CERTIFICATION Terminal Certifications ``` The user selects: ```text All Terminals ``` The application displays: ```text Terminal > Terminals > All Terminals ``` with the terminal management dashboard/table. --- # 61. Example — Switching to Disputes The user then swipes the Top Dock. ```text Terminal ↓ Payments ↓ Clearing ↓ Reconciliation ↓ Disputes ``` When Disputes becomes active: ```text Top Dock Disputes = ACTIVE ``` Sidebar immediately changes to: ```text DISPUTES CASE MANAGEMENT Dispute Dashboard Chargeback Cases Dispute Cases Case Search Case Details WORKFLOW Queues Workflow Configuration Approval Queue RULES & SLA Reason Codes & SLA Dispute Parameters Automation Rules ANALYTICS Win Rate Analytics Dispute Analytics Recovery Analytics ``` No Terminal menus remain visible. --- # 62. Example — Switching to Scheme Management The user selects: ```text Schemes & Network ``` The sidebar changes to: ```text SCHEMES & NETWORK SCHEME MANAGEMENT Scheme Dashboard Schemes Countries Currencies Products & Services (per-scheme: Cards Product, Authorization, Clearing, Settlement, + network value-added programs — see below) BIN / IIN Ranges EMV & CONTACTLESS EMV AIDs CAPKs Contactless Parameters NETWORK Network Routing Network Parameters COMMERCIAL Interchange Rates Scheme Fees DISPUTE PARAMETERS Reason Codes Dispute Parameters SETTLEMENT PARAMETERS Settlement Calendar Holiday Calendar CERTIFICATION & COMPLIANCE Certifications Compliance Records SCHEME INTELLIGENCE Bulletins MCC Rules ``` --- # 63. Error / Edge Cases The navigation should handle: ### Unauthorized Module If the user tries to access a module without permission: ```text Access Denied ``` The module should not appear in the Top Dock for normal navigation. ### Invalid URL If an invalid module/menu URL is accessed: * Display an appropriate error or redirect to the user's permitted default module. * Do not expose unauthorized navigation. ### Disabled Module If a module is disabled by tenant/product configuration: * Remove it from the Top Dock. * Existing direct URLs should show appropriate availability/access information. --- # 64. Performance Requirements Navigation switching should feel instantaneous. The UI should not reload the entire application shell when switching modules. The following should remain persistent where possible: * Header * Top Dock * User session * Global search * Notifications * Sidebar container * Application state Only the contextual navigation and main content should change. --- # 65. State Management The implementation should maintain at minimum: ```text selectedModule activeMenu expandedMenuGroups sidebarCollapsed ``` Example: ```text selectedModule = "terminal" activeMenu = "all-terminals" expandedMenuGroups = [ "terminals", "configuration" ] sidebarCollapsed = false ``` The implementation technology may determine the actual state-management approach. --- # 66. Security Requirements Navigation visibility is not a security boundary. The application must enforce authorization at the backend/API/service layer. Even if a user manually enters: ```text /acquiring/security/hsm ``` the system must verify: ```text User + Role + Permission + Tenant ↓ Authorization ``` before exposing data or actions. --- # 67. Tenant Awareness For a multi-tenant acquiring platform, navigation may also depend on tenant configuration. Example: ```text Tenant A Terminal Payments Settlement Disputes Tenant B Terminal Payments QR Reconciliation Risk ``` The navigation framework should support feature/module enablement at tenant level. --- # 68. Audit Requirements Navigation itself generally does not require audit logging. However, actions initiated from navigation pages may require normal application audit logging. Examples: * Key ceremony * Key rotation * MDR modification * Risk rule modification * Settlement approval * User role modification * Scheme parameter modification These remain governed by the respective module's audit requirements. --- # 69. Analytics / Usage Tracking The platform may optionally capture navigation analytics such as: * Module opened. * Menu opened. * Time spent. * Frequently accessed functions. * Search usage. * AI Agent usage. This can be used later to improve navigation. No personally sensitive information should be captured unnecessarily. --- # 70. Developer Implementation Guidance The developer should implement the navigation as a reusable framework rather than hard-coding each module independently. Conceptually: ```text Navigation Configuration | +-- Module | | | +-- Groups | | | +-- Menu Items | +-- Permissions | +-- Tenant Configuration ``` The UI should derive the Top Dock and Sidebar from this navigation configuration. This will make it easier to: * Add modules. * Remove modules. * Change menu ordering. * Add menu items. * Apply permissions. * Apply tenant-specific configuration. * Support future products. --- # 71. Suggested Navigation Configuration Model Conceptually: ```text Module id name icon order permission enabled Menu Group id module_id name order collapsible Menu Item id group_id name icon route permission order enabled ``` The exact database/configuration implementation is left to the development team. --- # 72. Acceptance Criteria ## Top Dock * [ ] Top-level modules are displayed in the Top Dock. * [ ] The Top Dock has a MacOS Dock-inspired visual design. * [ ] The active module is visually emphasized. * [ ] Hover produces a magnification/highlight effect. * [ ] Module selection works by click/tap. * [ ] Module switching supports appropriate gesture/scroll interaction. * [ ] Previous/next module navigation works. * [ ] Dock supports overflow. * [ ] Dock remains usable on different desktop resolutions. ## Contextual Sidebar * [ ] Sidebar displays only the selected module's menus. * [ ] Sidebar groups menus logically. * [ ] Groups can expand/collapse. * [ ] Active menu is highlighted. * [ ] Sidebar supports scrolling. * [ ] Sidebar can collapse. * [ ] Collapsed mode supports tooltips. * [ ] Sidebar does not display unrelated modules. ## Routing * [ ] Each menu item has a stable route. * [ ] URL determines active module. * [ ] URL determines active menu. * [ ] Browser refresh restores navigation state. * [ ] Browser back/forward works correctly. * [ ] Unauthorized URLs are protected. ## Permissions * [ ] Modules respect user permissions. * [ ] Menu items respect user permissions. * [ ] Tenant-level module enablement is supported. * [ ] Backend authorization is enforced independently. ## Accessibility * [ ] Keyboard navigation is supported. * [ ] Gesture navigation has an alternative. * [ ] Focus states are visible. * [ ] Icons have accessible labels. * [ ] Active states do not depend only on color. ## Responsive Behavior * [ ] Desktop layout supported. * [ ] Laptop layout supported. * [ ] Tablet/touch layout supported. * [ ] Sidebar can become a drawer on smaller screens. * [ ] Top Dock remains usable on smaller screens. --- # 73. Final Navigation Architecture The final proposed navigation architecture is: ```text ACQUIRING PLATFORM │ ▼ ┌─────────────────────┐ │ TOP MODULE DOCK │ └─────────────────────┘ │ ┌──────────┬──────────┬───────┼────────┬──────────┬──────────┐ ▼ ▼ ▼ ▼ ▼ ▼ ▼ Overview Merchant Terminal Payments Clearing Recon Disputes │ ▼ SELECTED MODULE │ ▼ ┌────────────────────────┐ │ CONTEXTUAL LEFT MENU │ │ │ │ Group │ │ Function │ │ Function │ │ │ │ Group │ │ Function │ │ Function │ └────────────────────────┘ │ ▼ MAIN APPLICATION PAGE ``` Additional top-level modules: ```text Risk & Fraud Schemes & Network Security & Administration AI Agent ``` --- # 74. Core UX Principle The entire navigation system should be designed around the following principle: > **The Top Dock answers "Which business area am I working in?"** > > **The Left Navigation answers "What can I do within this business area?"** > > **The Main Content answers "How do I perform that operation?"** Therefore: ```text TOP DOCK = BUSINESS DOMAIN LEFT SIDEBAR = BUSINESS FUNCTIONS MAIN CONTENT = OPERATION / WORKFLOW ``` This separation should remain consistent throughout the entire Acquiring Platform. --- # 75. Final Recommendation The navigation should not attempt to make the existing long menu visually smaller. Instead, the platform should fundamentally change the navigation model: ```text OLD MODEL One large menu ↓ 100+ functions ↓ Long scrolling sidebar ↓ High cognitive load NEW MODEL Mac-style Module Dock ↓ Select Business Domain ↓ Contextual Sidebar ↓ Relevant Functions Only ↓ Focused Workspace ``` This architecture should be used as the base navigation framework for the Acquiring Platform and extended as additional modules and functions are finalized. ``` ```