Skip to main content

53. Centralized Module Integration in Bot

Status: Accepted Date: 2025-07-06

Context​

The Mercury system is composed of numerous specialized modules (the "Pantheon"), such as Thoth for analysis, Minerva for data acquisition, Atlas for scheduling, and Hermes for exchange communication. We need a clear architectural pattern for how these modules are composed and orchestrated to form a functional trading bot. A chaotic approach where modules have complex, many-to-many dependencies on each other would create a "distributed monolith" that is hard to understand, test, and maintain.

Decision​

We will use the Centralized Orchestrator Pattern, with the mercury-bot module acting as the central point of integration. The mercury-bot application will be the only place where all the different trading system modules are imported and wired together.

Individual modules (Thoth, Minerva, etc.) should be designed to have minimal to no knowledge of each other. They should expose their functionality through well-defined services. The mercury-bot module's primary responsibility is to consume these services and orchestrate the flow of data and commands between them to execute the overall trading strategy.

Consequences​

Positive:

  • Clear Separation of Concerns: Each module focuses on its specific domain responsibility. The mercury-bot focuses solely on orchestration. This makes the system easier to reason about.
  • Reduced Coupling: Modules are not tightly coupled to each other. This allows them to be developed, tested, and potentially replaced independently.
  • Simplified Dependency Graph: The overall dependency graph is a much simpler "star" shape, with the mercury-bot at the center, rather than a complex "spaghetti" mesh. This makes it easier to trace data flows and understand the system's behavior.
  • Centralized Configuration: The composition of the final, running application is defined in one place, making it easier to manage different configurations or bot personalities.

Negative:

  • Potential Bottleneck: The mercury-bot module is a central point of failure and could become a performance bottleneck if not designed carefully.
  • God Object Risk: There is a risk that the mercury-bot module becomes a "God Object" that knows too much and has too many responsibilities, making it bloated and complex.

Mitigation:

  • Asynchronous Orchestration: The bot will rely heavily on asynchronous queue-based communication (adr://bullmq-queue-management) for orchestration rather than direct, synchronous method calls. This makes the orchestration non-blocking and more resilient.
  • Lean Orchestration Logic: The bot's role is strictly orchestration and wiring. Complex business logic should remain within the specialized modules. The bot should contain if-this-then-that logic, not complex algorithms. Code reviews will specifically watch for business logic "leaking" into the bot module.
  • Clear Module Boundaries: Strict enforcement of the rule that modules cannot import each other directly will prevent the architecture from degrading over time.