Initial production analytics foundation

2026-09-04 05:34:52 +02:00
commit f017d187eb
30 changed files with 1219 additions and 0 deletions
@@ -0,0 +1,41 @@
+# Architecture
+
+## Scope boundary
+
+ENLYZE is authoritative for raw process data. This service retrieves raw data
+only to calculate derived results and persists the results, their context, and
+the minimum state needed for incremental calculation. It does not mirror raw
+time series into PostgreSQL/TimescaleDB.
+
+## Components
+
+| Component | Responsibility | Must not do |
+| --- | --- | --- |
+| `enlyze` | Isolate ENLYZE retrieval and API-specific mapping | Leak assumed API schemas into calculations |
+| `domain` | Small, stable models for orders, provenance, metrics, and events | Encode database or HTTP details |
+| `calculations` | Versioned, testable operators such as integration and peak detection | Fetch data or write directly to a database |
+| `persistence` | Store results and calculation state through repository ports | Become a raw-data historian |
+| `cli` | Operator commands; first use is API exploration | Contain business calculations |
+| `service` | Future FastAPI composition/API layer | Require endpoints during bootstrap |
+
+## Result provenance
+
+Persisted metrics/events need machine and production-order context where
+available, article context, observed/result time or interval, calculation
+type/version, and the raw ENLYZE source interval used. A calculation run
+records operational metadata that ties a batch of results to its implementation
+version and source range.
+
+## Calculation instances
+
+Configuration declares a named calculation instance with a calculation type,
+version, and signal/context references. The engine selects a tested Python
+operator implementation for that type. This keeps configuration simple and
+avoids a generic expression language.
+
+## Incremental execution
+
+Future calculation state is stored per calculation instance and relevant
+context partition. It enables safe continuation (for example an open peak
+cycle), while the source interval recorded on results keeps a historical run
+reproducible by fetching ENLYZE data again.