# 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:

```text
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