Mercury's New Architecture - FDD and Divine Naming

After observing our development flow and documentation challenges, we're implementing key architectural improvements to make Mercury's development more maintainable and clear. This post documents these decisions for future reference.

Module Naming: The Divine Approach

We've chosen to use god names for our modules instead of functional names. This decision might seem unconventional, but it offers several significant advantages:

Why Divine Names?

1. Unique Namespacing

   • No collisions with technical terms
   • Clear, distinct module boundaries
   • Memorable and unambiguous references

2. AI Interaction

   • Creates unique contexts for AI understanding
   • Avoids confusion with general programming terms
   • Provides rich metaphorical framework for capabilities

3. Communication Clarity

   • "Fix in Apollo" vs "Fix in portfolio-analysis" (more specific)
   • "Minerva's API" vs "technical-analysis API" (clearer scope)
   • "THOTH integration" vs "knowledge-base integration" (unique identifier)

Current Divine Mapping

• APOLLO: Portfolio Analysis System
• MINERVA: Advanced Technical Analysis
• THOTH: Knowledge Retrieval and Augmentation
• ZEPHYR: Foundational Technical Analysis
• MORPHEUS: Shadow Portfolio System
• ATLAS: System Orchestration
• MAAT: Validation System
• KAIROS: Strategy Execution
• HERMES: News and Information
• DIKE: Tournament System
• CASSANDRA: Counter-algorithmic Strategies
• TYCHE: Sweet Spot Detection

Improved FDD Organization

We're moving from a centralized FDD to a module-level approach while maintaining visibility through Docusaurus.

Key Changes

1. One FDD Per Module

   mercury/
   ├── apollo/
   │   └── apollo.fdd.md
   ├── minerva/
   │   └── minerva.fdd.md
   ├── thoth/
   │   └── thoth.fdd.md

2. Docusaurus Integration

   • Custom plugin to collect .fdd.md files
   • Automatic documentation generation
   • Maintained searchability and cross-referencing

3. Documentation Structure

   • Module root contains single FDD file
   • High-level architecture in main docs
   • Clear ownership and update responsibility

FDD File Convention

Each *.fdd.md should contain:

# DEITY_NAME: System Purpose

## Overview

Brief description of the module's role in Mercury

## Divine Powers (Capabilities)

- Core functionalities
- Key features
- Integration points

## Sacred Artifacts (Key Components)

- Important classes/modules
- Critical algorithms
- Essential data structures

## Divine Interactions (Dependencies)

- Required modules
- External services
- Key integrations

## Prophecies (Roadmap)

- Planned features
- Known limitations
- Future improvements

Migration Plan

1. Phase 1: Documentation

   • Create template for module FDDs
   • Migrate existing documentation
   • Update Docusaurus configuration

2. Phase 2: Module Organization

   • Rename modules to divine names
   • Update import paths
   • Adjust CI/CD pipelines

3. Phase 3: Integration

   • Implement Docusaurus plugin
   • Set up documentation automation
   • Update build processes

Benefits of New Structure

1. Documentation and Code Proximity

   • FDD lives with its module
   • Natural updates during development
   • Clear ownership

2. Improved Maintainability

   • Reduced risk of outdated docs
   • Easier to keep in sync
   • Part of normal code review

3. Better Visibility

   • Integrated in Docusaurus
   • Searchable and connected
   • Clear module boundaries

4. Enhanced Communication

   • Unique, unambiguous module names
   • Rich metaphorical framework
   • Clear responsibility boundaries

Implementation Notes

1. Docusaurus Plugin

   // Example configuration
   const fddPlugin = {
     name: 'fdd-plugin',
     getPathsToWatch() {
       return ['../**/*.fdd.md'];
     },
     async loadContent() {
       // Collect FDD files
     },
     async contentLoaded({ content, actions }) {
       // Generate documentation
     },
   };

2. Module Headers

   /**
    * APOLLO: Portfolio Analysis System
    * Divine analyst of trading performance and metrics
    */

Conclusion

This new approach combines the benefits of distributed documentation with centralized visibility, while using a unique and powerful naming convention that aids both human and AI understanding. The divine naming scheme provides clear boundaries and rich context, while the module-level FDDs ensure documentation stays current and relevant.

May your code be blessed by the divine order of Mercury.