Analytics facts

This page explains how data reaches the analytics module. Nine modules each keep a file analytics_facts.py that declares one or more fact sets. The analytics module emits DescribeAnalyticsFacts on the EventBus, collects the answers in src/cluster_erp/modules/analytics/registry.py, validates them, and builds the catalogue every analysis reads. No module imports the analytics module, and the analytics module imports no module (src/cluster_erp/core/contracts.py:2055-2057).

In short¶

• A fact set (AnalyticsFactSet) names its module, a key, a label, its grain, the physical source table, its dimensions and measures, a read permission, and a live filter (src/cluster_erp/core/contracts.py:2126-2154).
• Each contributing module subscribes a handler to DescribeAnalyticsFacts that returns its fact sets (src/cluster_erp/modules/fleet/module.py:338-346).
• registry.collect emits the event, type-checks and validates every answer, refuses duplicates, and returns a FactCatalogue (src/cluster_erp/modules/analytics/registry.py:242-283).
• A caller sees only fact sets whose read_permission they hold (src/cluster_erp/modules/analytics/registry.py:100-109).

How it works¶

Collection path¶

sequenceDiagram
 participant S as AnalyticsService
 participant R as registry.collect
 participant B as EventBus
 participant M as module analytics_facts.py
 S->>R: catalogue(permission_codes, locale)
 R->>B: emit DescribeAnalyticsFacts
 B->>M: describe_analytics_facts(event)
 M-->>B: AnalyticsFactSet or list
 B-->>R: results of all handlers
 R->>R: type check, validate_fact, duplicate key check
 R-->>S: FactCatalogue
 S->>S: visible_to(permission_codes)

In prose:

1. AnalyticsService.catalogue calls registry.collect with the caller's locale (src/cluster_erp/modules/analytics/service.py:55-62).
2. collect emits DescribeAnalyticsFacts(source_module="analytics", locale=...). The locale only selects labels; keys stay language independent (src/cluster_erp/modules/analytics/registry.py:253, src/cluster_erp/core/contracts.py:2060-2073).
3. The EventBus calls every subscribed handler and returns their results. A handler that raises is logged and contributes nothing (src/cluster_erp/core/event_bus.py:83-96).
4. collect accepts one fact set or a list per handler. Anything else fails with ANALYTICS_INVALID_CONTRIBUTION (src/cluster_erp/modules/analytics/registry.py:254-266).
5. validate_fact checks each set; a second set with the same key fails instead of overwriting (src/cluster_erp/modules/analytics/registry.py:267-277).
6. visible_to keeps the sets whose read_permission is among the caller's permission codes (src/cluster_erp/modules/analytics/registry.py:100-109).

What a contribution declares¶

Contributions by module¶

Found with grep -rl analytics_facts src/cluster_erp/modules: nine modules, 13 fact sets.

Each module subscribes in its register_events, for example src/cluster_erp/modules/inventory/module.py:119-124, src/cluster_erp/modules/parties/module.py:134-139, and src/cluster_erp/modules/sales_orders/module.py:80-93. procurement subscribes two handlers, one per fact set (src/cluster_erp/modules/procurement/module.py:212-219). Every set uses the default live filter on deleted_at (grep live_filter in the nine files).

Some modules state in their docstrings what they leave out and why. inventory leaves stock levels out (src/cluster_erp/modules/inventory/analytics_facts.py:1-8), and fleet leaves cost per kilometre and CO2 out because a ratio of two aggregates is not additive (src/cluster_erp/modules/fleet/analytics_facts.py:1-11).

Why it is built this way¶

• The registry docstring states that the declaration is also the security allow-list: a user query may only reference a key, and a physical name never comes from user input (src/cluster_erp/modules/analytics/registry.py:1-9).
• It fails loudly because a silently skipped contribution would mean that a module's data never entered the analysis, discovered only through a wrong number (src/cluster_erp/modules/analytics/registry.py:11-16).
• The contract docstring calls live_filter mandatory because a set without it also counts deactivated records (src/cluster_erp/core/contracts.py:2139-2142).
• The module docstring states that a future module can contribute with no change in the analytics module (src/cluster_erp/modules/analytics/module.py:18-22).

Rules and boundaries¶

• A reference dimension must name its target so that labels resolve instead of showing raw ids (src/cluster_erp/modules/analytics/registry.py:131-135).
• rollup marks a low-cardinality reference dimension for the summary cells (src/cluster_erp/core/contracts.py:2092-2097); see reports, summaries, and cross.
• The analytics catalogue is rebuilt from the bus on each catalogue call (src/cluster_erp/modules/analytics/service.py:55-62).

Interaction with other parts¶

The full contract list is on the contracts reference; the bus is described on event bus.

Limits and open points¶

• The fleet fact sets sum total_cost and amount but declare no currency_field, so the mixed-currency gate does not apply to them (src/cluster_erp/modules/fleet/analytics_facts.py:98-104, src/cluster_erp/modules/fleet/analytics_facts.py:240-246).
• A handler that raises an exception is logged by the bus and its fact sets are missing from the catalogue without an error to the caller (src/cluster_erp/core/event_bus.py:94-96).

Terms introduced¶

Related pages¶

• Analytics module
• Recipes and query builder
• Fleet TCO, telematics, and analytics
• Inventory module
• Event bus

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