Skip to main content

80. Mythological Naming Convention for Modules

Status: Accepted Date: 2025-07-06

Context​

In a complex, modular system, the names of modules are a critical part of the shared language of the development team. Generic, technical names like DataService, AnalyticsEngine, or RuleProvider are functional but can be ambiguous, forgettable, and lack a strong conceptual boundary. This can make it harder to reason about the system's architecture and the specific responsibilities of each component.

Decision​

We will adopt a Mythological Naming Convention for all major modules within the Mercury trading system. Each core component will be named after a figure from mythology whose traditional domain aligns with the module's function.

Examples:

  • Apollo: The god of knowledge and prophecy. The module responsible for technical analysis and market data.
  • Dike: The goddess of justice and fair judgment. The module responsible for risk management, validation, and enforcing trading rules.
  • Minerva: The goddess of wisdom and strategic warfare. The module that runs trading tournaments and identifies market opportunities.
  • Morpheus: The god of dreams and shaping forms. The API gateway for all AI-related services, shaping data for LLMs.
  • Kairos: The god of the opportune moment. The centralized scheduling module.
  • Atlas: The titan who holds up the heavens. The data-gathering and signal-processing module.

This convention provides a strong, memorable, and unique identity for each component.

Consequences​

Positive:

  • Creates a Strong Ubiquitous Language: The names are memorable and create a powerful shorthand. Saying "Dike rejected the trade" is more evocative and clearer than "The risk management service returned a validation error."
  • Enforces Clear Conceptual Boundaries: Giving a module a strong thematic identity helps enforce the Single Responsibility Principle. If a piece of logic doesn't "feel like" an Apollo function, it probably doesn't belong in that module.
  • Improves Communication: The names are fun, engaging, and easy to talk about, which improves team communication and makes architectural discussions more intuitive.

Negative:

  • Initial Learning Curve: New developers will need to learn the mapping between the mythological names and their functions.
  • Unconventional: This is a non-standard practice that might be seen as unprofessional or confusing in some enterprise contexts.
  • Risk of Poor Analogy: If a name's mythological domain doesn't map well to its function, it can create more confusion than clarity.

Mitigation:

  • Clear Documentation: The FDD for each module will clearly state its purpose and the reason for its mythological name, onboarding new developers quickly. A central glossary of all module names will be maintained.
  • Internal Consistency: This convention is for our internal development. It does not leak into public-facing APIs or user documentation. The value is in team communication and architectural clarity.
  • Careful Selection: Names will be chosen carefully to ensure the analogy is strong and intuitive. The team must agree on the name and its fit before a module is created.