--- title: "Navigating the Workspace & Interface" description: "Documentation for Navigation" --- ## Table of Contents 1. [Overview](#1-overview) 2. [Layout & Structure](#2-layout--structure) 3. [Multi-Tab Workspace Navigation Mode](#3-multi-tab-workspace-navigation-mode) - [Keep-Alive State Preservation](#keep-alive-state-preservation) - [Drag-and-Drop Tab Organization](#drag-and-drop-tab-organization) - [Compact Density Selector](#compact-density-selector) 4. [Universal UI Hierarchy: Level 1 vs Level 2](#4-universal-ui-hierarchy-level-1-vs-level-2) - [Level 1: Root Data Grids](#level-1-root-data-grids) - [Level 2: Form Views & Headers](#level-2-form-views--headers) - [Bottom Fixed Action Bar & Cancel Behavior](#bottom-fixed-action-bar--cancel-behavior) 5. [Sidebar Accordion & Navigation Controls](#5-sidebar-accordion--navigation-controls) 6. [Global Search & Breadcrumbs](#6-global-search--breadcrumbs) 7. [AI Copilot Integrated Assistant](#7-ai-copilot-integrated-assistant) --- ## 1. Overview The **SoftSwitch Platform** delivers a high-productivity, web-based workspace designed for enterprise telecom administration, NOC engineers, and multi-tenant operators. The interface combines: - **Zero Page Refreshes**: Single-Page Application (SPA) with optimistic UI updates. - **Multi-Tab Workspace Navigation**: Open multiple modules simultaneously without losing unsaved form fields or pagination filters. - **Strict Visual Alignment**: Universal 56px headers, 4-column responsive form grids, and standardized bottom action bars. --- ## 2. Layout & Structure ``` ┌────────────────────────────────────────────────────────────────────────────────────────┐ │ [Logo] [Domain Selector ▼] [🔍 Search ( / )] [🌙] [🔔] [Copilot AI] [User Menu ▼]│ ├───────────────┬────────────────────────────────────────────────────────────────────────┤ │ SIDEBAR │ WORKSPACE TABS BAR │ │ │ [Extensions ×] [Domain: pbx.corp.com ×] [CDR Reports ×] [+ New Tab] │ │ 📁 PBX ├────────────────────────────────────────────────────────────────────────┤ │ ├─ Extensions│ LEVEL 1 / LEVEL 2 VIEW CONTAINER │ │ ├─ IVR │ │ │ ├─ Queues │ ┌────────────────────────────────────────────────────────────────────┐ │ │ └─ Routes │ │ Fixed Header (56px) [< List] Title: Edit Domain - pbx.corp.com │ │ │ │ ├────────────────────────────────────────────────────────────────────┤ │ │ 📁 Reports │ │ Tabs: [General] [Telephony Limits] [Retention] [Domain Aliases] │ │ │ ├─ CDR Logs │ │ │ │ │ └─ Live Calls│ │ FormBox (4-Column Form Grid) │ │ │ │ │ ┌──────────────────┬─────────────────┬──────────────┬────────────┐ │ │ │ 📁 Admin │ │ │ Label 1 (40px) │ Input 1 (38px) │ Label 2 │ Input 2 │ │ │ │ ├─ Tenants │ │ └──────────────────┴─────────────────┴──────────────┴────────────┘ │ │ │ └─ Security │ │ │ │ │ │ └────────────────────────────────────────────────────────────────────┘ │ │ ├────────────────────────────────────────────────────────────────────────┤ │ │ BOTTOM FIXED ACTION BAR: [Cancel Changes] [Save Changes] │ └───────────────┴────────────────────────────────────────────────────────────────────────┘ ``` --- ## 3. Multi-Tab Workspace Navigation Mode The workspace navigation mode transforms the single-view portal into a powerful multi-tasking desktop console. ### Keep-Alive State Preservation When working with complex telephony infrastructure, administrators frequently need to look up information in another module while editing a configuration (e.g. checking an Inbound Route or Extension while creating a new Queue). - **No Data Loss**: Switching between open tabs preserves all dirty form inputs, unsaved edits, and active validation errors. - **State Caching**: Data grid pagination, search query strings, and active filters remain in memory across tab switches. - **Tab Memory Management**: Closing a tab (`×`) frees its cached component state and unsubscribes real-time WebSocket listeners. ### Drag-and-Drop Tab Organization - Reorder tabs dynamically along the top tab bar by clicking and dragging. - Right-click or tab options menu allows: - **Close Tab**: Closes the current module. - **Close Other Tabs**: Retains only the focused module. - **Close Tabs to the Right**: Prunes trailing tabs. ### Compact Density Selector For operations center monitoring and high-density laptops, the workspace includes a compact mode switch in the top toolbar: - **Comfortable Mode (Default)**: Generous whitespace and standard padding for touch and desktop use. - **Compact Mode**: Reduces table row heights (`36px`), tightens form grid margins, and maximizes information density for large CDR and extension listings. --- ## 4. Universal UI Hierarchy: Level 1 vs Level 2 To maintain consistent user experience and prevent navigation disorientation, the platform strictly enforces Level 1 and Level 2 view semantics. ### Level 1: Root Data Grids Level 1 represents the root list of an entity (e.g., Extensions, Inbound Routes, Telephony Domains, Users). - **No Back Button**: Root views never display a `< Back` button because they sit at the top of their navigation hierarchy. - **Toolbar (`DataGridToolbar`)**: Features global table search, tenant filter, column visibility toggles, CSV export, and primary action buttons (e.g. `+ Add Extension`). - **Standardized Actions**: Each row features uniform action buttons: View, Edit, and Delete with referential integrity safeguards. ### Level 2: Form Views & Headers Level 2 represents item creation, inspection, or editing views. - **Fixed Header (`ModuleFormHeader`)**: Fixed 56px height (`min-h-[56px] py-2 px-4`) containing: - `< List` navigation button with direct return link to the parent Level 1 list. - 20px primary icon inside a subtle background container (`p-1 bg-primary/10 rounded-md`). - Clear, single-line title (e.g., `Edit Domain - pbx.company.com`) without redundant subtitles. - Contextual action icons (Duplicate, Quick List switcher, Add New). - **Pure Text Tabs**: Form tabs (``) contain text only (e.g. `{t('telephonyDomains.tabs.limits')}`). Graphic icons or images are prohibited in tabs to ensure uniform aesthetic cleanliness. - **4-Column Form Grid**: All form boxes utilize standard 4-column responsive layout (`grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-x-6 gap-y-3 items-start`). All field labels maintain a minimum height of `40px` (`min-h-[40px] flex items-center`) to anchor visual alignment across columns. ### Bottom Fixed Action Bar & Cancel Behavior Every Level 2 form view includes a bottom fixed bar (`FixedActionBar`): - **Cancel Button**: > [!IMPORTANT] > **Strict Cancel Button Standard:** > Clicking **Cancel** serves **only to revert uncommitted edits and restore the form to its original loaded values** (or default blank state during creation) while keeping the user on the form. > To leave the form and return to the list, the user clicks the `< List` button located in the top header. - **Save / Update Button**: Validates all active tabs, executes backend mutation via Fastify API, displays toast confirmation, and updates local state. --- ## 5. Sidebar Accordion & Navigation Controls - **Single-Open Accordion**: Expanding any module group in the sidebar (e.g., expanding *PBX Applications*) automatically collapses any other currently open group, preventing vertical sidebar clutter. - **Active Module Highlighting**: The active module is clearly highlighted with primary brand accent colors. - **Tenant Context Indicator**: Displays current tenant scope. System administrators can toggle tenant contexts on-the-fly. --- ## 6. Global Search & Breadcrumbs - **Global Quick Search**: Press `/` from anywhere in the application to summon the modal search palette: - Jump directly to extensions by typing an extension number (e.g. `1001`). - Search routes, DIDs, queues, users, or settings modules. - **Breadcrumb Trail**: Displays hierarchical location (e.g. `PBX → Inbound Routing → VIP PIN Routing`). --- ## 7. AI Copilot Integrated Assistant Accessible via the floating AI button or header icon: - **Platform Copilot**: Embedded conversational assistant powered by the Model Context Protocol (MCP). - **Context-Aware Assistance**: Automatically understands your active tenant, domain, and loaded form. - **Live Tool Execution**: Can query CDR logs, configure extensions, analyze SIP error codes, and suggest optimal queue configurations without leaving your active workspace. --- *Documentation updated: September 2026*