Global Search & Navigation
Relevant source files
The following files were used as context for generating this wiki page:
The Global Search & Navigation module provides the primary interface for users to traverse the application and locate patient records. It consists of a persistent navigation framework (the App Frame), a dynamic sidebar for workspace and feature switching, and a centralized patient search utility accessible via keyboard shortcuts or UI triggers.
This system ensures that clinicians can quickly move between worklists, dashboards, and administrative tools while maintaining context of their current workspace. The search functionality is designed for rapid patient identification using multiple identifiers such as name, date of birth, or medical record numbers.
Navigation Architecture
The navigation system is built around the AppFrame, which serves as the top-level layout for the entire application. It manages regions for navigation, content, and sidebars.
App Nav Components
The NavApp manages the persistent sidebar and workspace selection logic. It dynamically renders navigation links based on the user's role and the active workspace settings.
- Workspace Switcher: Located in the header, allows users to toggle between different clinics or organizations.
- Feature Links: Provides access to Worklists (Owned By, Schedule, Shared By), Dashboards, and Admin Tools (Clinicians, Programs).
- State Management: The navigation state (e.g., whether the menu is minimized) is persisted in
localStorage.
Sources: src/js/apps/globals/app-frame_app.js, test/integration/globals/app-nav.js:64-165, test/integration/globals/app-nav.js:330-482
The diagram above illustrates the structural hierarchy of the App Frame and how the Navigation App occupies the primary sidebar regions. Sources: src/js/apps/globals/app-frame_app.js, test/integration/globals/app-nav.js:64-150
Patient Search System
The Global Search functionality is implemented as a specialized application (SearchApp) that renders a modal dialog for querying the patient database.
Search Triggers and Modals
Search can be initiated via the navigation sidebar or by using the global keyboard shortcut /. The SearchApp manages the lifecycle of the PatientSearchModal.
- Input Handling: The search input supports debounced queries to the
/api/patientsendpoint. - Search Criteria: Users can search by Name, Date of Birth, Medical Record Number (MRN), Health Plan ID, or Phone Number.
- Results Display: Results are categorized and highlight the matching field (e.g., highlighting the specific identifier that matched the query).
Sources: src/js/apps/globals/search_app.js, src/js/views/globals/search/patient-search_views.js, test/integration/services/patient-quick-search.js:77-160
Search Data Flow
When a user types into the search input, a request is dispatched to the backend with specific filter parameters.
| Parameter | Description |
|---|---|
filter[search] | The primary text string for name or general search. |
include | Related entities to return (typically patient). |
limit | Controls the number of results displayed in the picklist. |
Sources: test/integration/services/patient-quick-search.js:52-75, test/integration/services/patient-quick-search.js:106-110
This sequence shows the interactive flow from user input to navigation upon selection. Sources: src/js/views/globals/search/patient-search_views.js, test/integration/services/patient-quick-search.js:106-135
Workspace Context and Permissions
Navigation and search results are heavily influenced by the active workspace and the user's permissions.
- Workspace Persistence: The
currentWorkspaceID is stored inlocalStorageto maintain state across sessions. - Permission Filtering:
- Admin Tools: Only visible to users with administrative roles (e.g.,
roleAdmin). - Add Patient: The "Add Patient" button in navigation is conditionally rendered based on the workspace setting
manual_patient_creation. - Worklists: Links like "Schedule" or "Owned By" are filtered to only show data relevant to the current clinician.
- Admin Tools: Only visible to users with administrative roles (e.g.,
Sources: test/integration/globals/app-nav.js:168-245, test/integration/globals/app-nav.js:316-328, src/js/i18n/en-US.yml:195-215
Navigation State Options
| Option | Type | Default | Description |
|---|---|---|---|
isNavMenuMinimized | Boolean | false | Persistence for sidebar width/collapsed state. |
currentWorkspace | String (UUID) | None | The active workspace context for API requests. |
help_url | String/Null | Config-driven | Destination for the "Help & Support" link. |
Sources: test/integration/globals/app-nav.js:176-180, test/integration/globals/app-nav.js:330-335
Workspace Switching Flow
Switching workspaces triggers a full reload of navigation-dependent data, ensuring clinicians do not see data from unauthorized clinics.
Summary
Global Search & Navigation provides the operational backbone for the RoundsWell frontend. By centralizing workspace management and patient discovery into a cohesive AppFrame, the system provides a consistent experience across diverse clinical workflows. The integration of role-based visibility and keyboard-accessible search allows for efficient navigation while maintaining strict data boundaries between workspaces.