Skip to main content

19. Mythological Naming Convention (Pantheon)

Status: Accepted Date: 2025-07-06

Context​

The Mercury trading system is composed of numerous specialized backend modules, each with a distinct responsibility (e.g., risk management, data analysis, scheduling). Using generic, technical names (e.g., RiskService, AnalysisEngine) can be dry and fails to create a strong, memorable mental model for the system's architecture.

Decision​

We will adopt a thematic naming convention for the core backend modules of the Mercury system, referred to as the "Pantheon." Each module will be named after a mythological figure whose attributes loosely correspond to the module's function.

For example:

  • Dike: The goddess of justice, for the risk management and compliance module.
  • Atlas: The titan who holds up the celestial heavens, for the data processing and signal generation module.
  • Morpheus: The god of dreams, for the AI-driven analysis and simulation module.

This convention applies only to the high-level NestJS modules within the mercury-backend.

Consequences​

Positive:

  • Thematic Cohesion: Creates a strong, unified theme for the project, making it more engaging and memorable.
  • Improved Recall: The evocative names can make it easier for developers to remember the purpose of each high-level module.
  • Strong Identity: Gives the project a unique and recognizable identity.

Negative:

  • Ambiguity: The connection between a mythological name and a module's function can be subjective and may not be immediately obvious to new developers.
  • Cognitive Overhead: Developers must learn the mapping between the names and their responsibilities.
  • Risk of Obscurity: Choosing overly obscure names could hinder rather than help understanding.

Mitigation:

  • Mandatory Documentation: Every Pantheon module must have a clear, concise, one-sentence description of its responsibility in its module definition file (e.g., dike.module.ts) and its FDD.md.
  • Central Glossary: Maintain a central, easily accessible glossary of all Pantheon modules and their roles in the main Mercury README.md and the domains/mercury/.cursor/rules/pantheon.mdc rule file.
  • Naming Council: Major new modules should have their names briefly discussed by the team to ensure they are reasonably intuitive and not overly obscure.