core/README.md

Reanimator

Reanimator is an event-driven hardware lifecycle platform for tracking servers and components from warehouse intake to production operation, failure analysis, and retirement.

It treats infrastructure like a medical record: every asset and component has a complete, queryable history of location, firmware, incidents, and reliability over time.

Project Tracking

Development milestones and execution checklist are in TODO.md.

What Reanimator Solves

• Inventory and shipment tracking
• Full component hierarchy (asset -> subcomponents)
• Time-based installation history (components can move between assets)
• Firmware and lifecycle timeline visibility
• Failure analytics (AFR, MTBF, reliability by part class)
• Spare-part planning
• Service ticket correlation
• Offline log ingestion with later synchronization

Core Principles

1. Events are the source of truth
   • Current state is derived from event history.
2. Hardware relationships are time-based
   • A component is linked to an asset through installation intervals, not permanent foreign keys.
3. Observations are not facts
   • Logs produce observations; observations produce derived events; events update state.
4. Data integrity first
   • Keep writes idempotent and preserve raw ingested data.

High-Level Architecture

LogBundle (offline)
      ->
Ingestion API
      ->
Parser / Observation Layer
      ->
Event Generator
      ->
Domain Model
      ->
MariaDB
      ->
API / UI / Connectors

Domain Model (MVP)

Organizational

• Customer: owner organization
• Project: infrastructure grouping within a customer
• Location (recommended): warehouse, datacenter, rack, repair center

Hardware

• Asset: deployable hardware unit (usually a server)
• Component: hardware part installed in an asset (SSD, DIMM, CPU, NIC, PSU)
• LOT: internal part classification for reliability analytics (for example, SSD_NVME_03.84TB_GEN4)
• Installation: time-bounded relationship between component and asset

installations.removed_at IS NULL means the installation is currently active.

Ingestion and Lifecycle

• LogBundle: immutable raw upload package
• Observation: parsed snapshot at collection time
• TimelineEvent: normalized lifecycle event (installed, removed, moved, firmware changed, ticket linked, etc.)
• FailureEvent: explicit failure record with source and confidence

Service Correlation

• Ticket: imported external service case
• TicketLink: relation to project, asset, or component

Suggested Database Tables (MVP)

customers
projects
locations

assets
components
lots
installations

log_bundles
observations
timeline_events

tickets
ticket_links
failure_events

Important Indexes

• components(vendor_serial)
• assets(vendor_serial)
• installations(component_id, removed_at)
• timeline_events(subject_type, subject_id, timestamp)
• observations(component_id)

API (MVP)

Ingestion

• POST /ingest/logbundle (must be idempotent)
• POST /ingest/failures

Assets and Components

• GET /assets
• GET /assets/{id}
• GET /assets/{id}/components
• GET /assets/{id}/tickets
• POST /machines/dispatch
• POST /machines/return-to-stock
• GET /components
• GET /components/{id}
• GET /assets/{id}/timeline
• GET /components/{id}/timeline

Organization Registry

• GET /customers, POST /customers
• GET /locations, POST /locations

Tickets

• POST /connectors/tickets/sync
• GET /tickets

Failures

• GET /failures

Analytics

• GET /analytics/lot-metrics
• GET /analytics/firmware-risk
• GET /analytics/spare-forecast

UI

• GET /ui (dashboard)
• GET /ui/assets, GET /ui/assets/{id}
• GET /ui/components, GET /ui/components/{id}
• GET /ui/tickets
• GET /ui/failures
• GET /ui/ingest
• GET /ui/analytics

Recommended Go Project Layout

cmd/reanimator-api
internal/domain
internal/repository
internal/ingest
internal/events
internal/connectors
internal/jobs
internal/api

Initial Delivery Plan

1. Registry: customers, projects, assets, components, LOT
2. Ingestion: logbundle upload, observation persistence, installation detection
3. Timeline: event derivation and lifecycle views
4. Service Correlation: ticket sync and linking

Future Extensions

• Predictive failure modeling
• Spare-part forecasting
• Firmware risk scoring
• Automated anomaly detection
• Rack-level topology
• Warranty and RMA workflows
• Multi-tenant support

Immediate Next Steps

1. Initialize Go module
2. Create base schema and indexes
3. Implement ingestion endpoint
4. Add observation-to-event derivation
5. Expose asset/component timeline APIs

Start with data model correctness, not UI.

Local Configuration

The API loads settings from environment variables and an optional config.json. If CONFIG_FILE is set, it will load that file. Otherwise it looks for config.json in the working directory if present. Environment variables override file values.

Database configuration can be provided as a full database_dsn or as discrete fields under database (user/password/host/port/name/params). If database_dsn is empty and no DATABASE_DSN env var is set, the discrete fields are used to build the DSN.

An example file is available as config.example.json.

Database Bootstrap

At this stage the project uses clean bootstrap instead of in-place schema migration for ownership changes.

Use:

make db-reset

This command drops and recreates the configured database, then applies the current schema from migrations/.