Admin Panel

Relevant source files

The following files were used as context for generating this wiki page:

• admin.tsx
• components/AdminDashboard.tsx
• components/admin/DataManagement.tsx
• components/admin/SystemsTable.tsx
• state/adminState.tsx
• components/admin/reconciliation/ReconciliationDashboard.tsx
• components/admin/AdminHistoricalAnalysis.tsx
• components/DiagnosticsModal.tsx
• STATE_MANAGEMENT_GUIDE.md
• ADMIN_ACCESS_CONTROL.md

The Admin Panel is a comprehensive internal dashboard for managing the BMSview application's data, systems, and health. It is a separate, standalone part of the application, served from admin.html and protected by Netlify Identity OAuth. This separation ensures that administrative functions and state are completely isolated from the public-facing user interface.

The panel provides tools for data reconciliation, system management, bulk operations, historical analysis, and running system diagnostics. It operates on its own state management context, AdminState, which is distinct from the main application's AppState. For more details on this architecture, see the State Management Guide.

Sources: admin.tsx, STATE_MANAGEMENT_GUIDE.md, ADMIN_ACCESS_CONTROL.md

Architecture

The Admin Panel is architecturally distinct from the main application. It is initialized in admin.tsx, which wraps the entire admin interface with its own AdminStateProvider. This provider supplies the AdminState context to all child components, ensuring a clean separation of concerns.

Sources: admin.tsx:14-19, STATE_MANAGEMENT_GUIDE.md

The following diagram illustrates the high-level component architecture of the Admin Panel.

State Management (AdminState)

The entire Admin Panel relies on a dedicated state context defined in state/adminState.tsx. This state object manages all data, UI state, and action statuses for the dashboard. It is managed via a useReducer hook, providing predictable state transitions.

Key properties of the AdminState include:

• Paginated data for systems and analysis history (systems, history).
• A complete cache of all history records for charting (historyCache).
• UI state flags (loading, error, expandedHistoryId).
• State for data management tasks like duplicate detection and bulk uploads.
• A comprehensive actionStatus object to track the loading state of numerous asynchronous operations.

The actionStatus object is central to the UI's responsiveness, allowing individual buttons and sections to show loading indicators for specific background tasks.

Sources: state/adminState.tsx:13-91, STATE_MANAGEMENT_GUIDE.md

actionStatus Tracking

The actionStatus object within AdminState tracks the state of various long-running operations. This allows the UI to provide granular feedback to the administrator.

Property	Description
isMerging	Tracks the merging of duplicate systems.
isDeletingUnlinked	Tracks the deletion of unlinked analysis records.
isScanning	Tracks the scanning process for duplicate analysis records.
isBulkLoading	Tracks the progress of a bulk file upload and analysis.
isRunningDiagnostics	Tracks the execution of system diagnostic tests.
isBackfilling	Tracks the process of backfilling data.
isCleaningLinks	Tracks the process of cleaning up system-to-analysis links.

Sources: state/adminState.tsx:61-80

The state of these actions is typically managed using a pair of dispatched actions, ACTION_START and ACTION_END, which toggle the corresponding boolean flag.

// Example of managing action state
dispatch({ type: 'ACTION_START', payload: 'isMerging' });
try {
  await mergeSystems(selectedSystemIds, primarySystemId);
  // ... handle success
} catch (error) {
  // ... handle error
} finally {
  dispatch({ type: 'ACTION_END', payload: 'isMerging' });
}

Sources: state/adminState.tsx:210-213, STATE_MANAGEMENT_GUIDE.md

Core Components

The AdminDashboard.tsx component serves as the central hub, composing several specialized child components to build the admin interface.

Sources: components/AdminDashboard.tsx

SystemsTable

This component is responsible for displaying a paginated and sortable table of all registered BMS systems.

Features:

• Pagination: Handles navigation through pages of system data.
• Selection: Allows admins to select multiple systems for bulk operations like merging.
• Editing: Provides an interface to open a modal for editing a system's details.
• Merging: Contains the UI logic to initiate a merge operation on selected systems.

Sources: components/admin/SystemsTable.tsx, components/AdminDashboard.tsx:125-163

The workflow for merging systems is illustrated below.

DataManagement

This component provides a suite of tools for performing bulk data operations.

Features:

• Scan for Duplicates: Initiates a backend process to find duplicate analysis records.
• Clear All Data: Provides functionality to wipe collections, with a confirmation step.
• Bulk Upload: An interface for uploading and analyzing multiple BMS screenshots at once.
• Data Integrity Actions: Includes buttons for cleaning jobs, auto-associating records, and fixing data inconsistencies.

Sources: components/admin/DataManagement.tsx

ReconciliationDashboard

This dashboard provides a centralized view for managing all Data Logger (DL-#) sources in the database. Its primary purpose is to identify and "adopt" orphaned data—analysis records that are not linked to any registered system.

The "Adopt System" workflow allows an admin to create a new BmsSystem directly from an orphaned DL-#, ensuring no data is lost.

Sources: DATA_RECONCILIATION_PR_SUMMARY.md, components/admin/reconciliation/ReconciliationDashboard.tsx

This flowchart shows the "Adopt Orphaned DL-#" workflow.

AdminHistoricalAnalysis

This component is a comprehensive "Analytics Command Center" that replaces the basic historical view. It integrates advanced trending intelligence, diagnostic tools, and enhanced charting capabilities.

It is composed of several sub-components:

• TrendingOverview: Displays key performance indicators like average charge/discharge rates and alert counts.
• HistoricalChart: An enhanced version of the chart with features like statistical bands, alert annotations, and solar overlay support.
• ToolsPanel: Provides action buttons to run diagnostics, trigger AI analysis, and predict maintenance.
• AlertAnalysis: A context-aware list of alerts that filters based on the visible time range in the chart.

Sources: HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md, components/admin/AdminHistoricalAnalysis.tsx

DiagnosticsModal

This modal displays the results of system health checks. It is triggered from the ToolsPanel within the AdminHistoricalAnalysis component or from the main dashboard. The modal presents a detailed, collapsible view of test results, including status, timing, and error messages for each diagnostic step.

Sources: ADMIN_DIAGNOSTICS_COMPLETION.md, components/DiagnosticsModal.tsx, components/AdminDashboard.tsx:291-300

Access Control

Access to the Admin Panel is managed at the page level. The entire admin.html page is protected by Netlify Identity, which requires users to authenticate via OAuth. Individual Netlify functions called by the admin panel do not perform their own authentication or authorization checks. The security model assumes that any user who can load admin.html is an authorized administrator.

Sources: ADMIN_ACCESS_CONTROL.md

Summary

The BMSview Admin Panel is a powerful, isolated environment for application management. Its architecture, centered around a dedicated AdminState context, ensures a clean separation from the public user interface. It provides administrators with a rich set of tools for data management, system monitoring, advanced analytics, and diagnostics, making it a critical component for maintaining the health and integrity of the application.