3.7 KiB
Project knowledge
Purpose
This service is a calculation and persistence layer between ENLYZE and Grafana. It must not become a second historian: raw process data stays in ENLYZE and is retrieved again when historical calculations need reproduction.
Core architectural decisions
- Python with a
src/package layout. - FastAPI is the preferred future service layer; no HTTP API is needed now.
- PostgreSQL with TimescaleDB is the target derived-data store.
- Grafana reads derived data from that database as an additional datasource.
- Secrets are environment variables only; no credentials or site-specific configuration are committed.
- Calculations are modular, testable Python implementations. Configuration declares instances; it is not a generic low-code language.
Peak-cycle detector
The first generic calculation is a timestamp-based PeakCycleDetector under
calculations. It is transport-independent and works for roll length, roll
weight, and similar cyclic signals. It maintains the maximum in an open cycle;
after a value falls below drop_ratio * current_peak, it emits that maximum
only after actual subsequent below-threshold observations support a continuous
hold_seconds interval. min_peak is a generic detector setting, along with
drop_ratio (0 < ratio < 1), hold_seconds (>= 0), and an explicit positive
max_sample_gap_seconds. Elapsed time, never a sample count, determines
confirmation. An interval longer than the configured maximum sample gap
restarts a reset candidate, so a timestamp gap is not
continuous-below evidence. Reset values can be negative rather than zero,
equal timestamps add no elapsed time, and backwards timestamps are rejected.
The maximum gap is required rather than inferred or defaulted, making each
source's continuity assumption explicit.
K7 roll length, variable bf81c547-dccf-4709-aee2-0f78366d1dfc (m), is the
first real-world validation case. The tested capture is continuous on a
10-second grid through its latest available sample; its shorter-than-requested
result was caused by an end time queried in the future, not observed time-series
gaps. The raw capture remains ignored and deterministic tests use synthetic
fixtures only.
Central domain context
Production orders connect machine, article/material, source interval, and derived results. Metrics and events must retain calculation type/version and source-time-range provenance.
Known versus unknown
Known from the ENLYZE UI: machine identity, operational/downtime state, current production order, article/material number, and process signals exist. It is not yet verified how, or whether, each is exposed by the ENLYZE API. Do not infer endpoint paths, authentication mechanisms, identifiers, paging, timestamp semantics, or signal payloads. The active open-question list is in docs/enlyze-api.md.
Exploration workflow
A deliberately generic, read-only CLI is available as
production-analytics enlyze raw PATH. It only makes GET requests, never
guesses endpoint schemas, and emits sanitized response metadata/body. The
operator must first obtain an authorized base URL, a verified safe path, and
the authentication method. Credentials reside in ignored secrets/enlyze.env;
the CLI parses simple assignments without sourcing/executing the file. Public
ENLYZE documentation verifies an Authorization: Bearer <ENLYZE_API_KEY>
authentication header; its value is never printed.
Unmodified captures are local in ignored data/raw/enlyze/. Fixtures written
to fixtures/enlyze/ are sanitized, but must still be reviewed before commit.
The deliverable is verified API observations and sanitized fixtures, not
production calculations or database ingestion.