Navigating the Workspace & Interface

Overview
Layout & Structure
Multi-Tab Workspace Navigation Mode
Universal UI Hierarchy: Level 1 vs Level 2
Sidebar Accordion & Navigation Controls
Global Search & Breadcrumbs
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]   │
└───────────────┴────────────────────────────────────────────────────────────────────────┘

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 (<TabsTrigger>) 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.

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