logpile/bible-local/04-data-models.md

04 — Data Models

Core contract: AnalysisResult

internal/models/models.go defines the shared result passed between parsers, collectors, server handlers, and exporters.

Stability rule:

• do not rename or remove JSON fields from AnalysisResult
• additive fields are allowed
• UI and exporter compatibility depends on this shape remaining stable

Key fields:

Field	Meaning
filename	Original upload name or synthesized live source name
source_type	archive or api
protocol	redfish, ipmi, or empty for archive uploads
target_host	Hostname or IP for live collection
source_timezone	Source timezone/offset if known
collected_at	Canonical collection/upload time
raw_payloads	Raw source data used for replay or diagnostics
events	Parsed event timeline
fru	FRU-derived inventory details
sensors	Sensor readings
hardware	Normalized hardware inventory

HardwareConfig

Main sections:

hardware.board
hardware.devices
hardware.cpus
hardware.memory
hardware.storage
hardware.volumes
hardware.pcie_devices
hardware.gpus
hardware.network_adapters
hardware.network_cards
hardware.power_supplies
hardware.firmware

network_cards is legacy/alternate source data. hardware.devices is the canonical cross-section inventory.

Canonical inventory: hardware.devices

hardware.devices is the single source of truth for device-oriented UI and Reanimator export.

Required rules:

1. UI hardware views must read from hardware.devices
2. Reanimator conversion must derive device sections from hardware.devices
3. UI/export mismatches are bugs, not accepted divergence
4. New shared device fields belong in HardwareDevice first

Deduplication priority:

Priority	Key
1	usable serial_number
2	bdf
3	keep records separate

Raw payloads

raw_payloads is authoritative for replayable sources.

Current important payloads:

• redfish_tree
• redfish_fetch_errors
• source_timezone

Normalized hardware fields are derived output, not the long-term source of truth.

Raw export package

/api/export/json produces a reopenable raw-export artifact.

Design rules:

• raw source stays authoritative
• uploads of raw-export artifacts must re-analyze from raw source
• parsed snapshots inside the bundle are diagnostic only