# 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](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.