The Site Listing module is a comprehensive administrative interface for managing physical locations (sites) within the Nimbly audit management system. It provides functionality for viewing, creating, editing, scheduling audits, and [bulk operationss](../Bulk Operation/BulkOperationOverview.md) on sites. The module is built using React with Redux for state management and implements role-based [access control](../Settings/Access control/AccessControlOverview.md).
1.1 Key Capabilities
Site Management: Create, view, edit, and delete sites
[Bulk Operationss](../Bulk Operation/BulkOperationOverview.md): Perform mass updates on multiple sites simultaneously
Scheduling: Configure audit [schedules](../Schedule/Schedule Listing/ScheduleListingOverview.md) for sites
Activity Tracking: Monitor site activity history and changes
Filtering & Sorting: Advanced search and organization capabilities
Performance Monitoring: Track site metrics and reporting status
2. Architecture
2.1 High-Level Architecture
graph TB
subgraph "Frontend Layer"
A[Site Pages] --> B[Site Components]
B --> C[Redux Store]
C --> D[Redux Actions]
D --> E[API Services]
end
subgraph "State Layer"
C --> F[Sites Reducer]
C --> G[Departments Reducer]
C --> H[Users Reducer]
C --> I[Firebase Auth]
end
subgraph "Backend Layer"
E --> J[REST APIs]
J --> K[Database]
end
style A fill:#e1f5e1
style C fill:#ffe1e1
style J fill:#e1e1ff
2.2 Module Structure
The site listing module follows a modular architecture pattern with clear separation of concerns:
graph TD
A[SitesPage] --> B[Layout]
A --> C[SitesManager]
A --> D[Modal Components]
C --> E[SitesListHeader]
C --> F[SiteTabNavigation]
C --> G[SitesList]
D --> H[SitesBulkModal]
D --> I[SitesScheduleModal]
D --> J[SitesScheduleEditModal]
D --> K[SitesBulkSchedule]
D --> L[SitesConfirmModal]
G --> M[SiteItem]
M --> N[Site Actions]
graph LR
A[Admin Dashboard] --> B[Sites Page]
B --> C[Site Details]
B --> D[Site Groups]
B --> E[Reports](../Reports/ReportsOverview.md)
B --> F[Bulk Operations]
C --> G[Edit Site]
C --> H[Schedule Audit]
C --> I[View Activity]
D --> J[Create Group]
D --> K[Manage Groups]
style B fill:#ffe1e1
style C fill:#e1f5e1
style D fill:#e1e1ff
4.3 Route Protection
All site-related routes implement:
Authentication Check: User must be logged in
Role Validation: User must have appropriate permissions
Feature Flags: Some routes depend on enabled features
Organization Context: Routes may behave differently based on organization settings
5. State Management
5.1 Redux Store Structure
The site listing module uses a comprehensive Redux architecture with actions, reducers, and sagas for async operations.
5.1.1 Sites State Interface
interface SitesState { // Data Management sites: Site[] site: Site | null orderedSites: Site[] allOrderedSites: Site[] paginationSites: Site[] // Pagination & Filtering pageIndex: number paginateSites: PaginatedSites processedSites: Site[] totalSites: number totalActive: number totalDisabled: number filterQuery: string // Sorting Configuration sortBy: string colorSelected: string name: SortDirection auditor: SortDirection primaryDepartment: SortDirection site: SortDirection reports: SortDirection status: SortDirection color: SortDirection supervisor: SortDirection updatedAt: SortDirection updatedBy: SortDirection // UI State modalVisible: ModalState selectedTab: string listActiveTab: 'active' | 'blocked' selectedSite: Site | null scrollPosition: number // Loading States isLoading: boolean isConfirmationLoading: boolean isSiteLoaded: boolean isSitesLoaded: boolean}
The module uses Redux Saga for handling async operations and side effects:
graph TB
A[Component Dispatch] --> B[Action Creator]
B --> C[Saga Watcher]
C --> D[Saga Worker]
D --> E[API Call]
E --> F[Success/Failure Action]
F --> G[Reducer Update]
G --> H[Component Re-render]
style C fill:#ffe1e1
style D fill:#e1f5e1
style E fill:#e1e1ff
5.3.1 Key Saga Functions
fetchPaginateSites(limit): Handles paginated data fetching with sorting and filtering
getPopulatedSites(action): Orchestrates the complete site loading process
fetchSiteById(action): Loads individual site with full details
updateSiteDepartments(action): Manages department associations for sites
5.4 Data Flow Patterns
5.4.1 Search and Filter Flow
sequenceDiagram
participant U as User
participant C as Component
participant S as Store
participant API as API
U->>C: Types in search box
C->>S: dispatch(setSitesFilterQuery)
S->>C: filterQuery updated
C->>S: dispatch(fetchPaginateSites)
S->>API: GET /sites/paginate?query=...
API->>S: Return filtered sites
S->>C: orderedSites updated
C->>U: Display filtered results
5.4.2 Pagination Flow
User clicks page navigation
setPageIndex action dispatched
fetchPaginateSites triggered with new page
API call with pagination parameters
State updated with new page data
Component re-renders with new sites
5.4.3 Modal Management Flow
All modals follow a consistent pattern:
User triggers modal action (button click)
Show modal action dispatched (showBulkModal, showScheduleModal, etc.)
Modal visibility state updated in Redux
Component conditionally renders modal based on state
Schedule Editing: Modify existing schedules in bulk
Conflict Detection: Prevent scheduling conflicts
7.2 User Workflows
7.2.1 Site Discovery Workflow
flowchart TD
A[User visits /admin/sites] --> B[Load Sites List]
B --> C{Sites Available?}
C -->|Yes| D[Display Sites Table]
C -->|No| E[Show Empty State]
D --> F[User can:]
F --> G[Search Sites]
F --> H[Filter by Department]
F --> I[Sort Columns]
F --> J[Navigate Pages]
G --> K[Update Results]
H --> K
I --> K
J --> K
K --> L[Display Updated List]
L --> M[User selects action]
M --> N[View Site Details]
M --> O[Schedule Audit]
M --> P[Block/Unblock Site]
M --> Q[View Activity History]
7.2.2 Bulk Operations Workflow
flowchart TD
A[User clicks Bulk Operations] --> B[Select Operation Type]
B --> C{Operation Type}
C -->|Create Sites| D[Upload Excel File]
C -->|Schedule Audits| E[Select Sites & Date]
C -->|Update Sites| F[Select Sites & Changes]
D --> G[Validate File Format]
G --> H{Valid?}
H -->|No| I[Show Errors]
H -->|Yes| J[Preview Changes]
E --> J
F --> J
J --> K[User Confirms]
K --> L[Execute Operation]
L --> M[Show Progress]
M --> N[Display Results]
N --> O[Update Site List]
7.2.3 Site Scheduling Workflow
flowchart TD
A[User clicks Schedule] --> B{Single or Multiple?}
B -->|Single Site| C[Quick Schedule Modal]
B -->|Multiple Sites| D[Bulk Schedule Modal]
C --> E[Select Date & Time]
D --> F[Upload Schedule Template]
E --> G[Choose Questionnaire]
F --> H[Validate Schedule Data]
G --> I[Assign Auditor]
H --> I
I --> J[Check Conflicts]
J --> K{Conflicts Found?}
K -->|Yes| L[Show Conflict Resolution]
K -->|No| M[Create Schedule]
L --> N[User Resolves]
N --> M
M --> O[Confirm Success]
O --> P[Update Calendar]
7.3 Advanced Features
7.3.1 Performance Optimization
Virtual Scrolling: Handles thousands of sites without performance degradation
Contextual Help: In-app guidance for complex operations
Interactive Tooltips: Real-time assistance for UI elements
7.3.3 Accessibility Features
Keyboard Navigation: Full keyboard support for all operations
Screen Reader Support: ARIA labels and semantic HTML
Color Contrast: WCAG-compliant color schemes
Focus Management: Proper focus handling in modals
7.3.4 Error Handling and Recovery
Graceful Degradation: Fallback UI for failed operations
Retry Mechanisms: Automatic retry for failed API calls
User Feedback: Clear error messages and resolution steps
State Recovery: Maintains user context during errors
8. Data Flow
8.1 Complete Data Flow Architecture
graph TB
subgraph "User Interface"
A[Site List View] --> B[Search Input]
A --> C[Filter Controls]
A --> D[Sort Headers]
A --> E[Pagination]
A --> F[Action Buttons]
end
subgraph "Component Layer"
B --> G[SitesListHeader]
C --> G
D --> H[SitesList]
E --> H
F --> I[Modal Components]
end
subgraph "State Management"
G --> J[Sites Actions]
H --> J
I --> J
J --> K[Sites Saga]
K --> L[Sites Reducer]
L --> M[Redux Store]
end
subgraph "API Layer"
K --> N[Site API Service]
N --> O[HTTP Client]
O --> P[REST Endpoints]
end
subgraph "Backend Services"
P --> Q[Site Service]
P --> R[Department Service]
P --> S[Schedule Service]
Q --> T[Database]
R --> T
S --> T
end
style M fill:#ffe1e1
style P fill:#e1f5e1
style T fill:#e1e1ff
8.2 State Update Flow
sequenceDiagram
participant UI as User Interface
participant AC as Action Creator
participant SG as Saga
participant API as API Service
participant RD as Reducer
participant ST as Store
UI->>AC: User Action (search, filter, etc.)
AC->>SG: Dispatch Action
SG->>API: API Call
API->>SG: Response Data
SG->>RD: Success/Error Action
RD->>ST: Update State
ST->>UI: Re-render Components
Note over SG,API: Async Operation
Note over RD,ST: Synchronous Update
8.3 Component Communication Patterns
8.3.1 Parent-Child Communication
graph TD
A[SitesPage] -->|Props| B[SitesManager]
B -->|Props| C[SitesListHeader]
B -->|Props| D[SitesList]
B -->|Props| E[Modal Components]
C -->|Events| B
D -->|Events| B
E -->|Events| B
B -->|Redux Actions| F[Global State]
F -->|State Updates| B
8.3.2 Redux State Flow
graph LR
A[Component] -->|dispatch| B[Action]
B --> C[Saga Middleware]
C -->|API Call| D[External Service]
D -->|Response| C
C -->|Success/Error| E[Reducer]
E --> F[Store]
F -->|New State| A
style C fill:#ffe1e1
style E fill:#e1f5e1
style F fill:#e1e1ff
9. Package Dependencies
9.1 Core Dependencies
Package
Version
Purpose
Usage in Module
react
^17.0.2
Core React library
All components and hooks
react-redux
^7.2.6
Redux React bindings
State management integration
redux
^4.1.2
State management
Global state container
redux-saga
^1.1.3
Async side effects
API calls and complex flows
react-router-dom
^5.3.0
Client-side routing
Navigation between views
styled-components
^5.3.3
CSS-in-JS styling
Component styling
9.2 UI and Interaction Dependencies
Package
Version
Purpose
Usage in Module
react-window
^1.8.6
Virtual scrolling
Large site list performance
react-toastify
^8.1.0
Toast notifications
User feedback and errors
react-i18next
^11.15.1
Internationalization
Multi-language support
@loadable/component
^5.15.2
Code splitting
Lazy loading of components
9.3 Firebase and Authentication
Package
Version
Purpose
Usage in Module
firebase
^9.6.1
Firebase SDK
Authentication and real-time data
react-redux-firebase
^3.10.0
Firebase Redux bindings
Firebase state integration
9.4 Utility Dependencies
Package
Version
Purpose
Usage in Module
lodash
^4.17.21
Utility functions
Data manipulation and formatting
moment
^2.29.1
Date/time handling
Schedule formatting and validation
axios
^0.25.0
HTTP client
API requests
9.5 Internal Dependencies
Package
Purpose
Usage in Module
@nimbly-technologies/nimbly-common
Shared utilities and constants
Enumerators, role resources, features
9.6 Development Dependencies
Package
Version
Purpose
Usage in Module
@types/react
^17.0.38
TypeScript types
Type safety for React components
@types/react-redux
^7.1.20
TypeScript types
Redux type safety
@types/styled-components
^5.1.20
TypeScript types
Styled components type safety
9.7 Bundle Size Impact
pie title Bundle Size Distribution
"React Core" : 35
"Redux Ecosystem" : 25
"UI Libraries" : 20
"Firebase" : 12
"Utilities" : 8
9.8 Performance Considerations
9.8.1 Bundle Optimization
Code Splitting: Components lazy-loaded using @loadable/component
Tree Shaking: Unused code eliminated during build
Dynamic Imports: Heavy components loaded on demand
9.8.2 Runtime Performance
Memoization: React.memo used for expensive components
Virtual Scrolling: react-window handles large datasets
Debouncing: Search inputs debounced to reduce API calls
// Environment-specific API URLsconst getApiUrl = () => { switch (process.env.NODE_ENV) { case 'development': return 'http://localhost:3001/api'; case 'staging': return 'https://staging-api.nimbly.io/api'; case 'production': return 'https://api.nimbly.io/api'; default: return 'http://localhost:3001/api'; }};
This comprehensive documentation covers all aspects of the Site Listing module, providing developers with the information needed to understand, maintain, and extend the functionality.