Skip to main content

120. Multi-Module Data Integration for Validation

Status: Accepted Date: 2025-07-06

Context​

The Maat module's purpose is to provide a holistic "truth" or quality assurance layer for the entire system. While the event-driven approach (adr://event-driven-bs-detection) is excellent for capturing real-time, localized anomalies, it's not sufficient for all types of validation.

Some of the most valuable insights come from cross-referencing data between modules. For example, comparing the results of a Dike tournament with the actual trading performance of the "winning" strategy in the Morpheus shadow engine can reveal deep truths about the effectiveness of our market selection algorithms. This kind of analysis requires Maat to be able to actively query and aggregate data from multiple, disparate sources.

Decision​

In addition to its passive, event-driven collection, the Maat module will actively integrate with and pull data from other key system modules as part of its scheduled validation and reporting workflows.

Specifically, Maat will have dedicated "Collector" services, such as:

  • DikeCollectorService: To fetch tournament results, including the inputs and outputs of AI comparisons.
  • MorpheusCollectorService: To fetch the performance data of shadow positions, especially those that were created based on tournament results or specific "spells".

These collectors will be invoked by a scheduled job (e.g., the BSReportService). They will query the respective services (DikeService, MorpheusService) for data from a specific time window, format it into a "BS Candidate" structure, and add it to the report for human review.

Consequences​

Positive:

  • Holistic, System-Wide View: Enables a much deeper level of analysis by connecting the dots between different parts of the system. It moves beyond simple anomaly detection to sophisticated cross-domain validation.
  • Uncovers Deeper Issues: This is how we can answer complex questions like, "Are our AI market comparisons actually leading to profitable trades?" or "Do high-confidence AI ratings correlate with higher win rates?" This is critical for validating the core hypotheses of the system.
  • Centralized Validation Logic: The logic for this cross-module analysis lives within Maat, which is its proper home. Dike and Morpheus remain focused on their core responsibilities and simply expose data via their standard service layers.

Negative:

  • Tighter Coupling: This approach creates a direct, runtime dependency from Maat to Dike and Morpheus. If the DikeService API changes, the DikeCollectorService in Maat may break.
  • Increased Complexity: The logic for the collector services can be complex, as it involves fetching, joining, and analyzing data from multiple sources.

Mitigation:

  • Service-Level Dependency: The coupling is at the service layer, which is a well-defined and versioned contract. The dependency is on the public API of the modules, not their internal implementation, which is a standard and acceptable form of coupling in a modular monolith.
  • Clear Separation of Concerns: The complexity is contained entirely within the collector services inside Maat. This keeps the core Maat reporting logic clean and focused. The collectors are specialized data-access components.
  • Asynchronous Execution: All of this data collection and analysis happens in a background job, so it has no performance impact on the real-time trading or API paths.