Module Engine and Data Contracts

Define and extend AutoDoctor PowerShell modules safely using the module engine contract, standardized result shape, and inter-module parameter model.
Categories:
Tags:

Who This Is For

  • Developers adding or modifying modules under agent/modules/.

Registration Contract

Each module registers exactly once:

Register-AutoDoctorModule -Name "Module Name" -Execute {
    param($MemoryObj, $CPUObj, $DiskObj, $NetworkObj, $ErrorObj, $ScriptStart)
    # Return a structured object
}

Engine Behavior

Invoke-AutoDoctorModules provides prior outputs by module name:

  • MemoryObj from Memory Analysis
  • CPUObj from CPU Analysis
  • DiskObj from Disk Analysis
  • NetworkObj from Network Analysis
  • ErrorObj from Event Log Analysis

Engine appends standardized metadata per module:

  • Module
  • Result
  • RuntimeSeconds
  • Error

And one synthetic row:

  • Module = "Engine Runtime" with ScriptRuntimeSeconds

Result Shape Expectations

Downstream code expects structured, non-scalar results where possible.

Examples:

  • CPU module returns CurrentCPULoadPercent, TopProcesses
  • Disk module returns DiskUsage, SMARTHealth, DiskIOSummary, HighDiskUsage
  • Root cause module returns HealthScore, HealthText, Summary, Details.DetectedIssues

Safe Authoring Guidelines

  • Use Invoke-Safe around system calls to avoid hard failures.
  • Keep return keys stable when possible.
  • Add new keys rather than renaming existing keys to avoid breaking dashboards/reports.
  • Keep module names stable because engine and post-processing reference them directly.

Quick Validation Pattern 

powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\agent\Initialize-AutoDoctor.ps1
powershell -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\agent\AutoDoctor.ps1

Validate in DB:

SELECT module_name, status, runtime_seconds FROM diagnostics ORDER BY id DESC LIMIT 20;

Next Steps