# 04 — Data Models

## AnalysisResult

`internal/models/` — the central data contract shared by parsers, collectors, exporters, and the HTTP layer.

**Stability rule:** Never break the JSON shape of `AnalysisResult`.
Backward-compatible additions are allowed; removals or renames are not.

Key top-level fields:

| Field | Type | Description |
|-------|------|-------------|
| `hardware` | `Hardware` | All normalized hardware inventory |
| `events` | `[]Event` | Diagnostic events from parsers |
| `sensors` | `[]Sensor` | Sensor readings |
| `raw_payloads` | `map[string]any` | Raw vendor data (e.g. `redfish_tree`) |
| `source` | `SourceMeta` | Origin metadata (type, protocol, host, date) |

### Hardware sub-structure

```
Hardware
  ├── board        BoardInfo       — server/motherboard identity
  ├── devices      []Device        — CANONICAL INVENTORY (see below)
  ├── cpus         []CPU
  ├── memory       []MemoryDIMM
  ├── storage      []Storage
  ├── gpus         []GPU
  ├── psus         []PSU
  ├── nics         []NetworkAdapter
  ├── pcie         []PCIeDevice
  └── firmware     []FirmwareInfo
```

---

## Canonical Device Repository (`hardware.devices`)

`hardware.devices` is the **single source of truth** for hardware inventory.

### Rules — must not be violated

1. All UI tabs displaying hardware components **must read from `hardware.devices`**.
2. The Device Inventory tab shows kinds: `pcie`, `storage`, `gpu`, `network`.
3. The Reanimator exporter **must use the same `hardware.devices`** as the UI.
4. Any discrepancy between UI data and Reanimator export data is a **bug**.
5. New hardware attributes must be added to the canonical device schema **first**,
   then mapped to Reanimator/UI — never the other way around.
6. The exporter should group/filter canonical records by section, not rebuild data
   from multiple sources.

### Deduplication logic (applied once by repository builder)

| Priority | Key used |
|----------|----------|
| 1 | `serial_number` — usable (not empty, not `N/A`, `NA`, `NONE`, `NULL`, `UNKNOWN`, `-`) |
| 2 | `bdf` — PCI Bus:Device.Function address |
| 3 | No merge — records remain distinct if both serial and bdf are absent |

### Device schema alignment

Keep `hardware.devices` schema as close as possible to Reanimator JSON field names.
This minimizes translation logic in the exporter and prevents drift.

---

## Source metadata (`SourceMeta`)

Carried by both `/api/status` and `/api/config`:

```json
{
  "source_type": "api",
  "protocol": "redfish",
  "target_host": "10.0.0.1",
  "collected_at": "2026-02-10T15:30:00Z"
}
```

Valid `source_type` values: `archive`, `api`
Valid `protocol` values: `redfish`, `ipmi` (empty is allowed for archive uploads)