Analytics module (analytics)

The analytics module in src/cluster_erp/modules/analytics/ analyses data that other modules declare to it over the EventBus. It imports no other module and knows no table of its own business; each module states which of its data can be analysed, and that declaration is also the allow-list for every query (src/cluster_erp/modules/analytics/module.py:15-27, src/cluster_erp/modules/analytics/registry.py:1-16). The module refuses to produce a number whenever it cannot produce a correct one (src/cluster_erp/modules/analytics/errors.py:1-13). This page is the overview; the sub-topics have their own pages.

At a glance¶

What the module does¶

• Collects the fact sets of all modules and validates them; a malformed contribution fails loudly (src/cluster_erp/modules/analytics/registry.py:242-283). See analytics facts.
• Builds safe aggregate queries from semantic keys and refuses wrong totals through correctness gates (src/cluster_erp/modules/analytics/query_builder.py:1-31). See recipes and query builder.
• Runs declarative preparation recipes and measures each step (src/cluster_erp/modules/analytics/recipe_engine.py:1-21).
• Profiles data, computes robust statistics and outlier screens, and runs hypothesis tests behind precondition gates (src/cluster_erp/modules/analytics/profiling.py:1-33, src/cluster_erp/modules/analytics/statistics.py:1-30, src/cluster_erp/modules/analytics/inference.py:1-34). See statistics and inference.
• Builds period series with visible gaps, baseline forecasts, and ABC and SBC classes (src/cluster_erp/modules/analytics/series.py:1-36, src/cluster_erp/modules/analytics/forecasting.py:1-45, src/cluster_erp/modules/analytics/classification.py:1-35). See forecasting and classification.
• Keeps saved analysis models, reports with result snapshots, pre-aggregated summary cells, and cross-fact comparisons (src/cluster_erp/modules/analytics/saved_models.py:1-14, src/cluster_erp/modules/analytics/reports.py:1-17, src/cluster_erp/modules/analytics/summaries.py:1-30, src/cluster_erp/modules/analytics/cross.py:1-15). See reports, summaries, and cross.

Sub-modules¶

The module has no sub-module folders. Its files group into these pages:

All routes live in one router with the prefix /analysis (src/cluster_erp/modules/analytics/routes.py:30).

Data model¶

Screens and metadata¶

get_metadata declares a sidebar group Analytics (Turkish Analitik) with eight custom sections: Explore, Analysis, Series & Baselines, Classification, Tests, Cross, Models, and Reports, plus a home widget Analytics of size 2x3 (src/cluster_erp/modules/analytics/module.py:75-161). The code comment states that every screen is a custom widget because the surfaces are instruments over the semantic layer, not entity lists (src/cluster_erp/modules/analytics/module.py:91-94). The catalogue the screens read carries labels, grains, additivity, and the monetary flag of each measure, so a new contributing module needs no interface code (src/cluster_erp/modules/analytics/service.py:63-125). See gated app bundles and home widgets.

Status and actions¶

The module declares no ActionMeta. Saved models and reports are deactivated through POST .../deactivate routes (src/cluster_erp/modules/analytics/routes.py:1001, src/cluster_erp/modules/analytics/routes.py:1120).

Business rules¶

• The permission gate applies twice: the catalogue shows only fact sets whose read_permission the caller holds, and a run looks the fact up in that filtered catalogue again. An unauthorised set answers as unknown, not as forbidden (src/cluster_erp/modules/analytics/service.py:1-7, src/cluster_erp/modules/analytics/registry.py:100-109, src/cluster_erp/modules/analytics/service.py:135-138).
• A query references only semantic keys; physical names come only from module declarations, and values are bound parameters (src/cluster_erp/modules/analytics/query_builder.py:5-10, src/cluster_erp/modules/analytics/schemas.py:1-11).
• Results are capped at 10000 rows and say when they were truncated (src/cluster_erp/modules/analytics/query_builder.py:60, src/cluster_erp/modules/analytics/service.py:150-155).
• Refusals carry machine-readable codes such as ANALYTICS_NON_ADDITIVE, ANALYTICS_MIXED_CURRENCY, and ANALYTICS_INSUFFICIENT_DATA (src/cluster_erp/modules/analytics/errors.py:21-43).

Events and queries¶

The module consumes no contract and produces 2, counted as on the fleet module page. It does not subscribe to anything; it emits DescribeAnalyticsFacts and collects the answers (src/cluster_erp/modules/analytics/module.py:57-61).

The collection path is on analytics facts; the full contract list is on the contracts reference.

Permissions¶

On top of these keys, each fact set carries its own read_permission of the contributing module (src/cluster_erp/core/contracts.py:2126-2154).

Privacy, retention, and history¶

The module has no privacy_handlers.py and no retention_handlers.py. Saved models and reports are deactivated, not deleted (src/cluster_erp/modules/analytics/saved_models.py:12-13, src/cluster_erp/modules/analytics/reports.py:14-15). Summary cells are derived data that the refresh deletes and rewrites; the docstring states that this is not the deletion of a record (src/cluster_erp/modules/analytics/summaries.py:18-20, src/cluster_erp/modules/analytics/summaries.py:245-295).

Analytics facts¶

This module has no analytics_facts.py; it is the consumer of the other modules' files. See analytics facts.

Settings and reference data¶

The statistical parameters are server settings with a prefix analytics_, for example analytics_quantile_type, analytics_min_n_for_zscore, and the ABC cut-offs (src/cluster_erp/config/settings.py:437-476). See settings reference. A background loop refreshes the summary cells at the interval analytics_summary_refresh_seconds (src/cluster_erp/server/app.py:461-470).

Tests¶

Found by name: 18 files tests/test_analytics_*.py and 12 files web-client/_e2e_analytics*.mjs.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Recipes and query builder
• Statistics and inference
• Forecasting and classification
• Reports, summaries, and cross
• Analytics facts
• API reference for this module

Verified against commit 92f8051 on 2026-11-13.