# 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 |
|-------|------|-------------|
| `filename` | `string` | Uploaded filename or generated live source identifier |
| `source_type` | `string` | `archive` or `api` |
| `protocol` | `string` | `redfish`, `ipmi`, or empty for archive uploads |
| `target_host` | `string` | BMC host for live collection |
| `collected_at` | `time.Time` | Upload/collection timestamp |
| `hardware` | `*HardwareConfig` | All normalized hardware inventory |
| `events` | `[]Event` | Diagnostic events from parsers |
| `fru` | `[]FRUInfo` | FRU/SDR-derived inventory details |
| `sensors` | `[]SensorReading` | Sensor readings |
| `raw_payloads` | `map[string]any` | Raw vendor data (e.g. `redfish_tree`) |

`raw_payloads` is the durable source for offline re-analysis (especially for Redfish).
Normalized fields should be treated as derivable output from raw source data.

### Hardware sub-structure

```
HardwareConfig
  ├── board        BoardInfo       — server/motherboard identity
  ├── devices      []HardwareDevice — CANONICAL INVENTORY (see below)
  ├── cpus         []CPU
  ├── memory       []MemoryDIMM
  ├── storage      []Storage
  ├── volumes      []StorageVolume  — logical RAID/VROC volumes
  ├── pcie_devices []PCIeDevice
  ├── gpus         []GPU
  ├── network_adapters []NetworkAdapter
  ├── network_cards    []NIC           (legacy/alternate source field)
  ├── power_supplies   []PSU
  └── 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 fields (stored directly on `AnalysisResult`)

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)

---

## Raw Export Package (reopenable artifact)

`Export Raw Data` does not merely dump `AnalysisResult`; it emits a reopenable raw package
(JSON or ZIP bundle) that carries source data required for re-analysis.

Design rules:
- raw source is authoritative (`redfish_tree` or original file bytes)
- imports must re-analyze from raw source
- parsed field snapshots included in bundles are diagnostic artifacts, not the source of truth