docs: introduce architecture bible and migrate README/claude knowledge

2026-02-21 20:37:10 +03:00
parent 88503d2457
commit ca762a658b
10 changed files with 294 additions and 208 deletions
--- a/claude.md
+++ b/claude.md
@@ -1,124 +1 @@
-# Reanimator AI Memory (Timeline + UI Rules)
-
-This file is the source of truth for timeline behavior, status logic, and related UI expectations.
-Any future AI change must preserve these rules unless explicitly changed by user request.
-
-## 1. Event Time Source Priority
-
-Use the real component event time, not ingest time, whenever available.
-
- `eventFallbackTime(actual, ingestedAt, collectedAt)` priority:
-1. `actual` (status/event timestamp from payload)
-2. `ingestedAt`
-3. `collectedAt` (last fallback)
-
- `collectedFallbackTime(collectedAt, ingestedAt)` is only for collected timestamp fields:
-1. `collectedAt`
-2. `ingestedAt`
-
-## 2. Status Event Time Parsing
-
-Component status event time must be resolved in this order:
-
-1. `status_changed_at`
-2. latest matching entry in `status_history` for current status
-3. latest parseable entry in `status_history`
-4. `status_checked_at`
-
-## 3. Failure Event Time Rules
-
-For `Critical` components:
-
- timeline status event type: `COMPONENT_FAILED`
- `failure_events.failure_time` must use resolved failure time (not raw ingest time)
- failure `external_id` includes that same failure time
-
-## 4. First Seen Logic
-
-`parts.first_seen_at` must always equal the earliest known ingest-derived component time.
-
- Candidate timestamps:
-1. `status_history[].changed_at` (all parseable entries)
-2. `status_changed_at`
-3. `status_checked_at`
-4. fallback via `eventFallbackTime(nil, ingestedAt, collectedAt)` if none exists
-
- DB update rule: keep minimum value over time
- If existing value is newer, overwrite with earlier incoming value
-
-## 5. Component Status Calculation (UI)
-
-`INSTALLED` and other non-status timeline events must never "heal" a failed component.
-
- Component status is computed only from the latest status event among:
-  - `COMPONENT_FAILED`
-  - `COMPONENT_WARNING`
-  - `COMPONENT_OK`
- `INSTALLED`, `REMOVED`, `FIRMWARE_CHANGED`, `FIRMWARE_INSTALLED`, etc. do not change component health state.
-
-## 6. Firmware Timeline Events
-
-For component firmware events:
-
- First observed firmware version: create `FIRMWARE_INSTALLED` (asset + component timeline pair)
- Later version change: create `FIRMWARE_CHANGED` (asset + component timeline pair)
-
-Details:
-
- For `FIRMWARE_INSTALLED`, `timeline_events.firmware_version` stores transition string:
-  - `- -> <installed_version>`
- For `FIRMWARE_CHANGED`, `timeline_events.firmware_version` stores installed/new version value.
- Firmware change detection reads previous observation with:
-  - `ORDER BY observed_at DESC, id DESC LIMIT 1 OFFSET 1`
-  - (current observation is already inserted in the same ingest transaction)
-
-## 7. Timeline Visual Semantics
-
-Color coding requirements:
-
- `REMOVED` must be yellow
- `COMPONENT_FAILED` must be red
- Warning/failure classes follow existing `timelineEventClass` rules
-
-## 8. Asset Page Structure
-
-Asset page must contain:
-
-1. `Current Components`
-2. `Previous Components` (directly below Current Components)
-3. `Movement & Events`
-
-`Previous Components` includes components previously installed on this asset and currently removed.
-
-## 9. Component Page Requirements
-
-Component page must include:
-
- Component card with current `Firmware`
- Installation history table:
-  - Asset
-  - Installed At
-  - Removed At
- Timeline metadata equivalent to asset timeline:
-  - Type
-  - Location
-  - Model
-  - Firmware (with fallback to latest known component firmware)
-
-## 10. Repository APIs Added for This Behavior
-
- `timeline.EventRepository.ListLatestBySubjectsAndEventTypes(...)`
- `registry.InstallationRepository.ListPreviousComponentsByAsset(...)`
- `registry.InstallationRepository.ListInstallationHistoryByComponent(...)`
-
-These methods are part of expected data flow for UI and status logic.
-
-## 11. Regression Guardrails
-
-Do not reintroduce any of these regressions:
-
- using ingest timestamp instead of real failure/event time when payload has a better timestamp
- letting `INSTALLED` mark failed components as healthy
- missing `Previous Components` section on asset page
- missing installation history on component page
- missing firmware information on component page timeline
+Read and follow `/Users/mchusavitin/Documents/git/core/bible/README.md` as the architecture source of truth.