Diagnostics Guru

Relevant source files

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

• components/DiagnosticsGuru.tsx
• netlify/functions/diagnostics-workload.cjs
• netlify/functions/utils/diagnostics-steps.cjs
• DIAGNOSTICS_GURU_IMPLEMENTATION.md
• DIAGNOSTICS_GURU_FIX_SUMMARY.md
• components/DiagnosticsModal.tsx
• ADMIN_DIAGNOSTICS_COMPLETION.md

The Diagnostics Guru is an automated, self-testing AI agent designed to systematically test all available Gemini tools within the BMSview application. It operates as an asynchronous background task, diagnoses failures, and submits detailed diagnostic reports to the AI Feedback dashboard. This system serves as the primary implementation of the Netlify Async Workloads pattern, providing a robust mechanism for long-running, non-blocking operations.

The Guru ensures system health by proactively detecting issues with core functionalities, such as data access, external API integrations, and AI-driven analysis. Its findings provide developers and administrators with actionable insights to maintain system reliability and performance.

Sources: DIAGNOSTICS_GURU_IMPLEMENTATION.md

Architecture

The Diagnostics Guru is built on an asynchronous, step-based architecture designed to handle long-running tasks that exceed standard serverless function execution limits. The process is initiated by an admin, managed by a central workload handler, and its state is persisted in a MongoDB collection.

This diagram illustrates the high-level interaction between the frontend, the Netlify function, and the database.

Key Components:

• DiagnosticsGuru.tsx: The frontend React component in the Admin Dashboard that allows an administrator to initiate and monitor the diagnostic process.
• diagnostics-workload.cjs: The main Netlify serverless function that acts as an API gateway. It handles start, step, and status actions to manage the lifecycle of the diagnostic job.
• diagnostics-steps.cjs: A utility module containing the implementation for each individual step of the diagnostic process, such as initializing the job, testing a tool, or finalizing the report.
• insights-jobs Collection: A MongoDB collection used to persist the state of the diagnostic workload, allowing the process to be stateless and survive function restarts.

Sources: DIAGNOSTICS_GURU_IMPLEMENTATION.md, components/DiagnosticsGuru.tsx, netlify/functions/diagnostics-workload.cjs, netlify/functions/utils/diagnostics-steps.cjs

Frontend Interaction

The user interface for the Diagnostics Guru is located within the Admin Dashboard. It provides a simple "Run Diagnostics" button and displays real-time progress as the background task executes.

Sources: components/DiagnosticsGuru.tsx, DIAGNOSTICS_GURU_IMPLEMENTATION.md

User Flow and Data Polling

The entire process is managed from the client-side through a series of API calls. The frontend initiates the workload, receives a unique ID, and then periodically polls for status updates until the job is complete.

This sequence diagram shows the communication flow between the user's browser and the backend Netlify function.

UI State Management

The DiagnosticsGuru.tsx component maintains the state of the diagnostic run, which is updated with each polling response. Defensive default values are used to prevent UI errors if the backend response is incomplete during initialization.

The following table details the structure of the status object used by the frontend.

Field	Type	Description	Default Value
workloadId	string | null	The unique identifier for the diagnostic job.	null
status	string	The current status of the job (pending, running, completed, failed).	'idle'
currentStep	string	The name of the step currently being executed.	'initialize'
stepIndex	number	The index of the current step.	0
totalSteps	number	The total number of steps in the workload.	0
progress	number	The completion percentage (0-100).	0
message	string	A human-readable message about the current progress.	''
results	any[]	An array of results from each test.	[]
feedbackSubmitted	any[]	A list of feedback items submitted to the AI Feedback dashboard.	[]
summary	object | null	The final summary object when the job is complete.	null
error	string | null	An error message if the job failed.	null

Sources: components/DiagnosticsGuru.tsx:21-46, DIAGNOSTICS_GURU_FIX_SUMMARY.md

Backend Workload

The backend logic is orchestrated by the diagnostics-workload.cjs Netlify function, which manages the job's lifecycle through different action types specified in the request body.

Sources: netlify/functions/diagnostics-workload.cjs

API Actions

The function exposes a single endpoint that behaves differently based on the action parameter.

Action	Method	Endpoint	Request Body	Response
start	POST	/.netlify/functions/diagnostics-workload	{ "action": "start" }	{ "success": true, "workloadId": "..." }
step	POST	/.netlify/functions/diagnostics-workload	{ "action": "step", "workloadId": "..." }	{ "success": true, "message": "Step executed" }
status	POST	/.netlify/functions/diagnostics-workload	{ "action": "status", "workloadId": "..." }	A full status object containing the current state of the job.

Sources: netlify/functions/diagnostics-workload.cjs:48-112, DIAGNOSTICS_GURU_IMPLEMENTATION.md

State Persistence

Job state is stored in the insights-jobs MongoDB collection to ensure the process can continue across multiple serverless function invocations. Each step of the workload reads the current state, performs its action, and writes the updated state back to the database.

A typical job state document has the following structure:

{
  "jobId": "diag_timestamp_random",
  "mode": "diagnostics",
  "status": "running",
  "state": {
    "workloadType": "diagnostics",
    "currentStep": "test_tool",
    "stepIndex": 3,
    "totalSteps": 14,
    "toolsToTest": ["request_bms_data", "..."],
    "toolIndex": 3,
    "results": [
      { "toolName": "getWeatherData", "status": "success" }
    ],
    "failures": [],
    "categorizedFailures": {},
    "feedbackSubmitted": [],
    "progress": 42,
    "message": "Testing getSystemAnalytics..."
  }
}

Sources: DIAGNOSTICS_GURU_IMPLEMENTATION.md

Diagnostic Steps

The diagnostic process is broken down into a sequence of discrete steps, executed in order by the workload handler. This design allows for independent retries and clear progress tracking.

This flowchart shows the sequence of steps from initialization to completion.

Tools Tested

The Guru systematically tests all 11 core AI tools to ensure they are functioning correctly.

1. request_bms_data
2. getWeatherData
3. getSolarEstimate
4. getSystemAnalytics
5. predict_battery_trends
6. analyze_usage_patterns
7. calculate_energy_budget
8. get_hourly_soc_predictions
9. searchGitHubIssues
10. getCodebaseFile
11. listDirectory

Sources: DIAGNOSTICS_GURU_IMPLEMENTATION.md

Failure Analysis

After running all tests, the Guru analyzes any failures and categorizes them to aid in debugging.

Category	Description
network_error	Network or timeout issues.
database_error	Failures related to MongoDB.
invalid_parameters	Errors from parameter validation.
no_data	The tool returned an empty result.
token_limit	The AI context window was exceeded.
circuit_open	The circuit breaker for the tool was open.
unknown	Any other uncategorized error.

Sources: DIAGNOSTICS_GURU_IMPLEMENTATION.md

AI Feedback Integration

A key function of the Diagnostics Guru is to automatically report its findings. It uses the submitAppFeedback tool to create entries in the AI Feedback dashboard. To distinguish these automated reports from other sources, it uses a special guruSource tag.

This system allows administrators to easily filter and review all diagnostic reports, validate the findings, and create GitHub issues for confirmed bugs.

Guru Source Tags:

• diagnostics-guru (orange badge 🔧)
• battery-guru (blue badge 🔋)
• visual-guru (purple badge 📊)
• And others for different AI agents.

Sources: DIAGNOSTICS_GURU_IMPLEMENTATION.md

Conclusion

The Diagnostics Guru is a critical internal tool for maintaining the health and reliability of the BMSview application's AI features. By automating the testing of all Gemini tools and providing detailed, categorized failure reports, it enables proactive issue detection and faster debugging. Furthermore, its implementation serves as a successful validation of the Netlify Async Workloads pattern, paving the way for future long-running background tasks within the project.