Initial production analytics foundation

README.md

@@ -0,0 +1,69 @@
+# production-analytics
+
+`production-analytics` is a small Python service that derives production
+analytics from ENLYZE data for Grafana. ENLYZE remains the authority for raw
+process data; this project persists only derived metrics, events, relevant
+production-order context, and calculation state.
+
+## Status
+
+This repository includes a read-only ENLYZE API exploration CLI. It contains
+no verified ENLYZE operation wrappers, database migrations, or HTTP endpoints.
+
+## Intended flow
+
+```text
+ENLYZE (raw data) -> retrieval boundary -> calculations -> TimescaleDB -> Grafana
+                                      \-> calculation provenance/state
+```
+
+Production orders are the primary attribution context for results. Every
+persisted result will ultimately be traceable to its machine, order/article
+context, source time range, and calculation implementation version.
+
+## Development
+
+Requires Python 3.11 or newer. Install the project and development tools:
+
+```bash
+python3 -m pip install -e '.[dev]'
+pytest
+ruff check .
+```
+
+Copy `.env.example` to `.env` for public/local configuration documentation.
+Put real ENLYZE credentials only in `secrets/enlyze.env`, which is ignored.
+The CLI reads that file by default without executing it; it accepts only simple
+`KEY=VALUE` lines (quoted values are supported). Environment variables may be
+used instead when appropriate. Never pass keys as command-line arguments.
+
+The generic request command only performs `GET` requests and requires the
+operator to provide an API path that is known to be safe and authorized:
+
+```bash
+production-analytics enlyze raw /verified/path --pretty
+production-analytics enlyze raw /verified/path --save-fixture response.json
+```
+
+Public ENLYZE documentation verifies Bearer-token authentication. Put
+`ENLYZE_API_KEY='...'` in the local secret file; the exploration client sends
+it as an `Authorization: Bearer …` header and never prints that header/value.
+
+The second command saves a sanitized, reviewable fixture under
+`fixtures/enlyze/` by default. Raw captures belong in the ignored
+`data/raw/enlyze/` directory and must not be committed.
+
+The OpenAPI server URL is `https://app.enlyze.com/api/`; its operation paths
+begin with `/v2/`. Set `ENLYZE_BASE_URL` to that server URL, not to an
+operation path. The documented read-only time-series operation is exposed for
+exploration as `production-analytics enlyze timeseries`.
+
+The current Compose file has no application service, so it deliberately does
+not pass ENLYZE credentials to TimescaleDB. A future application service should
+use `env_file: ./secrets/enlyze.env` rather than copying secrets into Compose.
+
+`docker compose up -d timescaledb` is an optional local database design for a
+future persistence milestone. It is not required for the bootstrap tests.
+
+See [PROJECT_KNOWLEDGE.md](PROJECT_KNOWLEDGE.md) for durable project context
+and [docs/roadmap.md](docs/roadmap.md) for the implementation sequence.