State Management

Relevant source files

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

• state/appState.tsx
• state/adminState.tsx
• hooks/useAnalyticsData.ts
• hooks/useInsightsPolling.ts
• HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md
• DATA_RECONCILIATION_PR_SUMMARY.md

BMSview employs React's built-in Context API with the useReducer hook for state management. The architecture intentionally separates state into two distinct, independent contexts: one for the public-facing application and another for the administrative dashboard. This separation enhances performance, security, and maintainability by ensuring that the state for each part of the application is isolated and only re-renders relevant components.

This approach avoids external state management libraries like Redux or Zustand, leveraging standard React patterns that are type-safe, dependency-free, and easy for new developers to understand.

Sources: STATE_MANAGEMENT_GUIDE.md, GEMINI.md

Architecture: Dual-Context Model

The application is split into two entry points, index.html (public app) and admin.html (admin dashboard), each with its own state provider. This ensures that the complex and data-heavy admin state does not impact the performance of the lightweight public-facing app.

The following diagram illustrates the separation of the two state contexts.

Public Application State (AppState)

The AppState context manages the state for the main user-facing interface where users upload and analyze BMS screenshots. It is defined in state/appState.tsx and is concerned with analysis results, system registration, and fetching public data like registered systems and analysis history.

State Shape (AppState)

The AppState interface contains fields for managing the analysis process and user interactions.

Field	Type	Description
analysisResults	DisplayableAnalysisResult[]	A list of current analysis results from file uploads.
isLoading	boolean	Global loading indicator for the analysis process.
error	string | null	Stores any error messages related to analysis.
isRegisterModalOpen	boolean	Controls the visibility of the system registration modal.
registrationContext	{ dlNumber: string } | null	Context for registering a new system, typically the DL number.
registeredSystems	PaginatedResponse<BmsSystem> | BmsSystem[]	A list of BMS systems visible to the user.
analysisHistory	PaginatedResponse<AnalysisRecord> | AnalysisRecord[]	A list of historical analysis records.
isSyncing	boolean	Indicates if a local-first sync operation is in progress.
lastSyncTime	Record<string, number>	Timestamps of the last successful sync for different data collections.

Sources: state/appState.tsx:18-47, PHASE_COMPLETION_VERIFICATION.md

Analysis Flow

The following diagram shows the sequence of actions dispatched during a typical file analysis workflow in the public app.

Admin Dashboard State (AdminState)

The AdminState is significantly more complex, designed to manage the data-intensive administrative dashboard. It handles paginated data, complex UI states, bulk operations, diagnostics, and numerous asynchronous actions. It is defined in state/adminState.tsx.

State Shape (AdminState)

The state is organized into several logical sections.

Section	Key Fields	Description
Paginated Data	systems, history, historyCache, totalSystems, systemsPage	Manages data for paginated tables and a full cache for charting.
UI State	loading, error, expandedHistoryId, editingSystem	Controls general loading indicators, errors, and UI element states.
System Management	selectedSystemIds, primarySystemId	Manages state for bulk operations like merging systems.
Data Management	duplicateSets, bulkUploadResults, linkSelections	Handles state for data integrity tasks like finding duplicates and linking records.
Action Status	actionStatus: { isMerging, isDeletingUnlinked, ... }	A map of boolean flags to track the status of over 15 distinct asynchronous operations, preventing concurrent actions and providing specific UI feedback.
Diagnostics	isDiagnosticsModalOpen, diagnosticResults, selectedDiagnosticTests	Manages the state for the system diagnostics tool.

Sources: state/adminState.tsx:25-96

Action Status Pattern

To manage the many independent, long-running tasks in the admin panel, AdminState uses an actionStatus object. This pattern allows the UI to show specific loading states for different actions (e.g., "Merging...", "Deleting...") without a global isLoading flag.

// state/adminState.tsx:70-95
actionStatus: {
    isMerging: boolean;
    isDeletingUnlinked: boolean;
    deletingRecordId: string | null;
    isSaving: boolean;
    // ... and 10+ more flags
};

An action is managed by dispatching ACTION_START and ACTION_END actions.

State-Driven Custom Hooks

The application uses custom hooks to encapsulate complex stateful logic, often combining local component state with the global AppState or AdminState.

useAnalyticsData

This hook, defined in hooks/useAnalyticsData.ts, is responsible for fetching and preparing all data required for the "Historical Analysis" section of the admin dashboard. It is a consumer of AdminState.

Responsibilities:

1. Fetches system analytics from the system-analytics endpoint when selectedSystemId changes.
2. Filters the global history from AdminState to only include records for the selected system.
3. Extracts and deduplicates alerts to be displayed as annotations on the chart.
4. Provides a refreshAnalytics function to manually re-fetch data.

The hook returns a structured object for the component to consume:

// hooks/useAnalyticsData.ts:20-27
return {
  analyticsData,
  isLoading,
  error,
  filteredHistory,
  visibleAlerts,
  refreshAnalytics,
};

Sources: hooks/useAnalyticsData.ts, HISTORICAL_ANALYSIS_IMPLEMENTATION_COMPLETE.md

useInsightsPolling

This hook, defined in hooks/useInsightsPolling.ts, manages the polling process for asynchronous jobs, such as bulk analysis. It periodically calls the get-job-status API to check for completion.

State Machine:
The hook follows a simple state machine for its pollingStatus.

Conclusion

BMSview's state management is a practical and effective implementation of React's native capabilities. The dual-context architecture provides a clear separation of concerns between the public and admin sections of the application, which is crucial for performance and maintainability. The use of the useReducer hook ensures predictable state transitions, while custom hooks like useAnalyticsData and useInsightsPolling encapsulate complex, state-driven logic, keeping components clean and focused on rendering. The patterns employed, such as the actionStatus map, demonstrate a thoughtful approach to handling the complex UI requirements of a data-heavy administrative dashboard.

Sources: STATE_MANAGEMENT_GUIDE.md, GEMINI.md