Bootstrap reanimator chart viewer
This commit is contained in:
Mikhail Chusavitin
@@ -0,0 +1,22 @@
|
||||
# Project Bible
|
||||
|
||||
`bible-local/` is the single source of truth for everything specific to Reanimator Chart.
|
||||
|
||||
## Read Order
|
||||
|
||||
1. `architecture/system-overview.md`
|
||||
2. `architecture/data-model.md`
|
||||
3. `architecture/api-surface.md`
|
||||
4. `architecture/runtime-flows.md`
|
||||
5. `architecture/ui-information-architecture.md`
|
||||
6. `decisions/README.md`
|
||||
|
||||
## Structure
|
||||
|
||||
- `architecture/system-overview.md` - product scope, non-goals, stack direction
|
||||
- `architecture/data-model.md` - viewer domain model and rendering data rules
|
||||
- `architecture/api-surface.md` - embeddable handler/API surface
|
||||
- `architecture/runtime-flows.md` - render flow and invariants
|
||||
- `architecture/ui-information-architecture.md` - page structure and UI rules
|
||||
- `decisions/README.md` - architectural decision log format
|
||||
- `decisions/2026-03-15-read-only-schema-preserving-viewer.md` - initial product decision
|
||||
@@ -0,0 +1,35 @@
|
||||
# API Surface
|
||||
|
||||
## Primary Integration Style
|
||||
|
||||
The package is intended to be embedded by other Go applications.
|
||||
|
||||
Expected package shape:
|
||||
|
||||
- `viewer.RenderHTML(snapshot []byte) ([]byte, error)`
|
||||
- `viewer.NewHandler(...) http.Handler`
|
||||
|
||||
Exact signatures may change during implementation, but the integration model is fixed:
|
||||
|
||||
- embedding app provides the JSON
|
||||
- chart renders HTML
|
||||
|
||||
## Expected Runtime Endpoints
|
||||
|
||||
These endpoints are expected for the standalone binary only:
|
||||
|
||||
- `GET /` - viewer page
|
||||
- `POST /render` - accept one Reanimator JSON payload and return rendered HTML or JSON render result
|
||||
- `GET /healthz` - basic process health
|
||||
|
||||
## UI Route Rules
|
||||
|
||||
- No multi-product navigation
|
||||
- No upload wizard with preview/confirm/execute stages
|
||||
- No collector/API-connect workflow
|
||||
- No background job polling API
|
||||
|
||||
## Response Rules
|
||||
|
||||
- HTML pages are read-only views of one snapshot
|
||||
- API responses must not modify or augment the input payload semantics
|
||||
@@ -0,0 +1,54 @@
|
||||
# Data Model
|
||||
|
||||
## Canonical Input
|
||||
|
||||
The canonical input is one Reanimator hardware JSON snapshot.
|
||||
|
||||
The viewer does not own the schema. The Reanimator JSON contract remains external to this repository.
|
||||
|
||||
## Viewer Data Model
|
||||
|
||||
The viewer uses a presentation model derived directly from the input JSON:
|
||||
|
||||
- top-level snapshot metadata
|
||||
- ordered top-level sections
|
||||
- table definitions per section
|
||||
- raw field values
|
||||
|
||||
## Rendering Rule
|
||||
|
||||
The viewer is schema-preserving, not schema-owning.
|
||||
|
||||
- Known sections have a preferred order.
|
||||
- Known important fields may have a preferred column order.
|
||||
- Every field present in the input must remain visible.
|
||||
- Unknown fields must not be dropped.
|
||||
|
||||
## Section Model
|
||||
|
||||
Section types expected initially:
|
||||
|
||||
- singleton object section, for example `board`
|
||||
- array-of-object section, for example `cpus`
|
||||
- nested grouped section, for example `sensors.{fans,power,temperatures,other}`
|
||||
|
||||
## Column Rules
|
||||
|
||||
For array sections:
|
||||
|
||||
1. collect the union of keys present across all rows
|
||||
2. place known fields first
|
||||
3. append unknown fields after known fields
|
||||
4. render absent values as empty cells
|
||||
|
||||
## Special Field Handling
|
||||
|
||||
- `status` is rendered as a colored badge
|
||||
- arrays such as `mac_addresses` may be rendered as line-separated values or badges inside one cell
|
||||
- nested values such as `status_history` may be rendered in expandable detail blocks inside one cell
|
||||
|
||||
## Persistence
|
||||
|
||||
There is no database and no canonical stored state in v1.
|
||||
|
||||
The viewer operates on the in-memory snapshot provided by the embedding application or local file input.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Runtime Flows
|
||||
|
||||
## Render Snapshot Flow
|
||||
|
||||
1. receive one Reanimator JSON snapshot from the caller
|
||||
2. decode the payload into generic/object structures without dropping unknown fields
|
||||
3. identify known top-level sections
|
||||
4. build presentation sections in preferred order
|
||||
5. for each array section, build the union of keys across rows
|
||||
6. order columns with known fields first and unknown fields after
|
||||
7. render the page
|
||||
|
||||
## Status Presentation Flow
|
||||
|
||||
1. read the raw `status` value from the payload
|
||||
2. normalize only for presentation matching (`OK`, `Warning`, `Critical`, `Unknown`, `Empty`)
|
||||
3. apply status badge class
|
||||
4. do not change the raw value shown to the user
|
||||
|
||||
## Unknown Field Invariant
|
||||
|
||||
1. if a field exists in the input, it must remain visible somewhere in the output
|
||||
2. unknown fields may appear after known fields in a section table
|
||||
3. unknown top-level sections may be rendered after known sections
|
||||
4. the viewer must never silently discard fields because they are new or unexpected
|
||||
|
||||
## Non-Augmentation Invariant
|
||||
|
||||
1. do not compute aggregate health summaries unless they already exist in the JSON
|
||||
2. do not derive warnings/failures counters
|
||||
3. do not infer statuses for missing fields
|
||||
4. do not merge or rewrite source values
|
||||
|
||||
## Simplicity Rule
|
||||
|
||||
1. prefer server-rendered HTML
|
||||
2. keep JavaScript optional and presentation-only
|
||||
3. do not introduce a frontend framework without a concrete present need
|
||||
@@ -0,0 +1,47 @@
|
||||
# System Overview
|
||||
|
||||
## Product
|
||||
|
||||
Reanimator Chart is a small Go web viewer for Reanimator hardware JSON snapshots.
|
||||
|
||||
It is designed to be embedded as a module in other Go applications that already collect audit data and emit Reanimator-compatible JSON.
|
||||
|
||||
## Active Scope
|
||||
|
||||
- Render one Reanimator JSON snapshot as HTML
|
||||
- Read-only presentation of top-level metadata and hardware sections
|
||||
- Tabular rendering for arrays such as `cpus`, `memory`, `storage`, `pcie_devices`, `power_supplies`, and sensor subsections
|
||||
- Status color coding for fast scanning
|
||||
- Lightweight section navigation
|
||||
- Standalone HTML rendering or embeddable HTTP handler
|
||||
|
||||
## Explicitly Out Of Scope
|
||||
|
||||
- Parsing vendor logs or archives
|
||||
- Collecting hardware data
|
||||
- Converting non-Reanimator formats
|
||||
- Editing or mutating snapshot data
|
||||
- Derived health analytics not present in the input JSON
|
||||
- Timeline/history reconstruction
|
||||
- Database storage
|
||||
- Background jobs, upload pipelines, or batch processing UI
|
||||
|
||||
## Product Rules
|
||||
|
||||
- The viewer must display the input snapshot as-is.
|
||||
- The viewer may format values for presentation, but may not invent new data.
|
||||
- Unknown fields must still be visible in the UI.
|
||||
- Known sections may have a preferred visual order, but payload content remains authoritative.
|
||||
|
||||
## Tech Direction
|
||||
|
||||
- Go HTTP server / embeddable handler
|
||||
- Server-rendered HTML
|
||||
- Minimal client-side JavaScript only for presentation helpers such as expand/collapse and sticky section navigation
|
||||
- No SPA framework unless a concrete need appears later
|
||||
|
||||
## Local Run
|
||||
|
||||
Expected future command:
|
||||
|
||||
- `go run ./cmd/reanimator-chart`
|
||||
@@ -0,0 +1,63 @@
|
||||
# UI Information Architecture
|
||||
|
||||
## Page Structure
|
||||
|
||||
The page should contain:
|
||||
|
||||
1. header
|
||||
2. snapshot metadata strip
|
||||
3. compact section navigation
|
||||
4. ordered content sections
|
||||
|
||||
## Header
|
||||
|
||||
Show only essential context:
|
||||
|
||||
- product name
|
||||
- target host if present
|
||||
- collected time if present
|
||||
- source type and protocol if present
|
||||
|
||||
## Section Order
|
||||
|
||||
Preferred order:
|
||||
|
||||
1. `board`
|
||||
2. `firmware`
|
||||
3. `cpus`
|
||||
4. `memory`
|
||||
5. `storage`
|
||||
6. `pcie_devices`
|
||||
7. `power_supplies`
|
||||
8. `sensors`
|
||||
9. unknown sections
|
||||
|
||||
## Section Presentation
|
||||
|
||||
- singleton object sections render as key-value table
|
||||
- array sections render as compact data tables
|
||||
- sensors render as separate subtables for `fans`, `power`, `temperatures`, and `other`
|
||||
|
||||
## Visual Rules
|
||||
|
||||
- status badges:
|
||||
- green for `OK`
|
||||
- yellow/amber for `Warning`
|
||||
- red for `Critical`
|
||||
- gray for `Unknown`
|
||||
- light gray for `Empty`
|
||||
- do not color arbitrary non-status fields
|
||||
- keep tables dense and scan-friendly
|
||||
|
||||
## Complexity Limits
|
||||
|
||||
- no multi-tab application shell
|
||||
- no dashboard analytics
|
||||
- no wizard-like workflow
|
||||
- no collector controls
|
||||
|
||||
## Accessibility
|
||||
|
||||
- tables must remain readable on desktop and mobile
|
||||
- section navigation must work without JavaScript
|
||||
- color must not be the only status indicator; always show text
|
||||
@@ -0,0 +1,37 @@
|
||||
# Decision: Read-Only Schema-Preserving Viewer
|
||||
|
||||
**Date:** 2026-03-15
|
||||
**Status:** active
|
||||
|
||||
## Context
|
||||
|
||||
A separate repository is being created to display Reanimator JSON snapshots in a simpler and more reusable way than the existing `logpile` UI.
|
||||
|
||||
The goal is to let other Go applications embed the viewer module and present Reanimator snapshot data without duplicating UI work.
|
||||
|
||||
There was an explicit requirement that the viewer must show all JSON fields and must not add new computed data.
|
||||
|
||||
## Decision
|
||||
|
||||
Reanimator Chart is defined as a small read-only web viewer for one Reanimator JSON snapshot.
|
||||
|
||||
It will:
|
||||
|
||||
- render source data as-is
|
||||
- preserve unknown fields
|
||||
- use simple section navigation and tables
|
||||
- color-code device statuses for presentation only
|
||||
|
||||
It will not:
|
||||
|
||||
- perform collection or parsing of raw vendor logs
|
||||
- run upload/API-connect/convert workflows
|
||||
- compute aggregate health summaries unless they are already present in the input JSON
|
||||
- become a generic analyzer product
|
||||
|
||||
## Consequences
|
||||
|
||||
- The viewer architecture must stay minimal and server-rendered by default.
|
||||
- The rendering layer must be tolerant of schema evolution.
|
||||
- UI code must not silently drop unexpected fields.
|
||||
- `logpile` patterns for upload, convert, collectors, and job management are out of scope here.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Architectural Decision Log
|
||||
|
||||
Each file in this directory records one architectural decision.
|
||||
|
||||
Format:
|
||||
|
||||
```markdown
|
||||
# Decision: <short title>
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Status:** active | superseded by YYYY-MM-DD-topic.md
|
||||
|
||||
## Context
|
||||
Why the decision was needed.
|
||||
|
||||
## Decision
|
||||
What was decided.
|
||||
|
||||
## Consequences
|
||||
What this requires or forbids going forward.
|
||||
```
|
||||
Reference in New Issue
Block a user