production-analytics/PROJECT_KNOWLEDGE.md

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.

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.