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>
This commit is contained in:
Mikhail Chusavitin
2026-02-20 14:15:35 +03:00
parent 82ee513835
commit fcd57c1ba9
21 changed files with 1289 additions and 2391 deletions

View File

@@ -0,0 +1,82 @@
# 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)