Files

Mikhail Chusavitin fcd57c1ba9 docs: introduce project Bible and consolidate all architecture documentation

- Create docs/bible/ with 10 structured chapters (overview, architecture,
  API, data models, collectors, parsers, exporters, build, testing, decisions)
- All documentation in English per ADL-007
- Record all existing architectural decisions in docs/bible/10-decisions.md
- Slim README.md to user-facing quick start only
- Replace CLAUDE.md with a single directive to read and follow the Bible
- Remove absorbed files: REANIMATOR_EXPORT.md, docs/INTEGRATION_GUIDE.md,
  and all vendor parser README.md files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-02-20 14:15:35 +03:00

2.7 KiB

Raw Blame History

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

All UI tabs displaying hardware components must read from hardware.devices.
The Device Inventory tab shows kinds: pcie, storage, gpu, network.
The Reanimator exporter must use the same hardware.devices as the UI.
Any discrepancy between UI data and Reanimator export data is a bug.
New hardware attributes must be added to the canonical device schema first, then mapped to Reanimator/UI — never the other way around.
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:

{
  "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)

2.7 KiB Raw Blame History