logpile/docs/bible/10-decisions.md

10 — Architectural Decision Log (ADL)

Rule: Every significant architectural decision must be recorded here before or alongside the code change. This applies to humans and AI assistants alike.

Format: date · title · context · decision · consequences

---

ADL-001 — In-memory only state (no database)

Date: project start Context: LOGPile is designed as a standalone diagnostic tool, not a persistent service. Decision: All parsed/collected data lives in Server.result (in-memory). No database, no files written. Consequences:

• Data is lost on process restart — intentional.
• Simple deployment: single binary, no setup required.
• JSON export is the persistence mechanism for users who want to save results.

---

ADL-002 — Vendor parser auto-registration via init()

Date: project start Context: Need an extensible parser registry without a central factory function. Decision: Each vendor parser registers itself in its package's init() function. vendors/vendors.go holds blank imports to trigger registration. Consequences:

• Adding a new parser requires only: implement interface + add one blank import.
• No central list to maintain (other than the import file).
• go test ./... will include new parsers automatically.

---

ADL-003 — Highest-confidence parser wins

Date: project start Context: Multiple parsers may partially match an archive (e.g. generic + specific vendor). Decision: Run all parsers' Detect(), select the one returning the highest score (0–100). Consequences:

• Generic fallback (score 15) only activates when no vendor parser scores higher.
• Parsers must be conservative with high scores (70+) to avoid false positives.

---

ADL-004 — Canonical hardware.devices as single source of truth

Date: v1.5.0 Context: UI tabs and Reanimator exporter were reading from different sub-fields of AnalysisResult, causing potential drift. Decision: Introduce hardware.devices as the canonical inventory repository. All UI tabs and all exporters must read exclusively from this repository. Consequences:

• Any UI vs Reanimator discrepancy is classified as a bug, not a "known difference".
• Deduplication logic runs once in the repository builder (serial → bdf → distinct).
• New hardware attributes must be added to canonical schema first, then mapped to consumers.

---

ADL-005 — No hardcoded PCI model strings; use pci.ids

Date: v1.5.0 Context: NVIDIA and other vendors release new GPU models frequently; hardcoded maps required code changes for each new model ID. Decision: Use the pciutils/pciids database (git submodule, embedded at build time). PCI vendor/device ID → human-readable model name via lookup. Consequences:

• New GPU models can be supported by updating pci.ids without code changes.
• make build auto-syncs pci.ids from submodule before compilation.
• External override via LOGPILE_PCI_IDS_PATH env var.

---

ADL-006 — Reanimator export uses canonical hardware.devices (not raw sub-fields)

Date: v1.5.0 Context: Early Reanimator exporter read from Hardware.GPUs, Hardware.NICs, etc. directly, diverging from UI data. Decision: Reanimator exporter must use hardware.devices — the same source as the UI. Exporter groups/filters canonical records by section; does not rebuild from sub-fields. Consequences:

• Guarantees UI and export consistency.
• Exporter code is simpler — mainly a filter+map, not a data reconstruction.

---

ADL-007 — Documentation language is English

Date: 2026-02-20 Context: Codebase documentation was mixed Russian/English, reducing clarity for international contributors and AI assistants. Decision: All maintained project documentation (docs/bible/, README.md, CLAUDE.md, and new technical docs) must be written in English. Consequences:

• Bible is authoritative in English.
• AI assistants get consistent, unambiguous context.

---

ADL-008 — Bible is the single source of truth for architecture docs

Date: 2026-02-23 Context: Architecture information was duplicated across README.md, CLAUDE.md, and the Bible, creating drift risk and stale guidance for humans and AI agents. Decision: Keep architecture and technical design documentation only in docs/bible/. Top-level README.md and CLAUDE.md must remain minimal pointers/instructions. Consequences:

• Reduces documentation drift and duplicate updates.
• AI assistants are directed to one authoritative source before making changes.
• Documentation updates that affect architecture must include Bible changes (and ADL entries when significant).

---