Skip to main content

Codomyrmex Project Architecture

This document provides a high-level overview of the Codomyrmex project architecture. The project is designed to be modular, allowing for independent development and functionality of its various components while ensuring they can interoperate effectively.

Core Philosophy​

  • Modularity: Each distinct area of functionality (e.g., AI code editing, data visualization, static analysis) is encapsulated within its own module.
  • Extensibility: New modules can be added to the system with relative ease by following a defined template and set of conventions.
  • Interoperability: Modules can communicate and share data/functionality through well-defined interfaces, primarily the Model Context Protocol (MCP) for AI agent interactions and Python APIs for programmatic use.
  • Consistency: Standardized documentation, testing practices, and development guidelines are applied across all modules.

Key Architectural Components​

graph TD
    A[User/Developer Interface (e.g., IDE Plugin, CLI)] --> B{Codomyrmex Core Orchestrator (Conceptual)}
    
    B --> MCP[Model Context Protocol Layer]
    
    MCP --> M1[AI Code Editing Module]
    MCP --> M2[Build Synthesis Module]
    MCP --> M3[Code Execution Sandbox Module]
    MCP --> M4[Data Visualization Module]
    MCP --> M5[Git Operations Module]
    MCP --> M6[Pattern Matching Module]
    MCP --> M7[Static Analysis Module]
    MCP --> M_Other[Other Modules...]

    subgraph PythonAPIs [Python APIs / SDK]
        P1[AI Code Editing API]
        P2[Build Synthesis API]
        P3[Code Execution API]
        P4[Data Visualization API]
        P5[Git Operations API]
        P6[Pattern Matching API]
        P7[Static Analysis API]
    end

    M1 --> P1
    M2 --> P2
    M3 --> P3
    M4 --> P4
    M5 --> P5
    M6 --> P6
    M7 --> P7

    subgraph SharedServices [Shared Utility Modules]
        SS1[Logging & Monitoring Module]
        SS2[Environment Setup Module]
        SS3[Model Context Protocol Module (Defines the protocol itself)]
    end

    M1 -- Consumes --> SS1
    M2 -- Consumes --> SS1
    M3 -- Consumes --> SS1
    M4 -- Consumes --> SS1
    M5 -- Consumes --> SS1
    M6 -- Consumes --> SS1
    M7 -- Consumes --> SS1

    M1 -- Consumes --> SS3
    M2 -- Consumes --> SS3
    M3 -- Consumes --> SS3
    M4 -- Consumes --> SS3
    M5 -- Consumes --> SS3
    M6 -- Consumes --> SS3
    M7 -- Consumes --> SS3

    M_All[All Modules] -- Uses --> SS2 {for setup/env checks}

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#ccf,stroke:#333,stroke-width:2px
    style MCP fill:#lightgrey,stroke:#333,stroke-width:2px
    style PythonAPIs fill:#lightyellow,stroke:#333,stroke-width:2px
    style SharedServices fill:#e6ffe6,stroke:#333,stroke-width:2px

Modules​

Each module is a self-contained unit focusing on a specific domain. It typically includes:

  • Core logic (Python code, scripts, etc.).
  • Its own README.md, API_SPECIFICATION.md, MCP_TOOL_SPECIFICATION.md, SECURITY.md, CHANGELOG.md, and USAGE_EXAMPLES.md.
  • A docs/ directory for technical_overview.md and tutorials.
  • A tests/ directory for unit and integration tests.
  • A pyproject.toml for module-specific dependencies.

Model Context Protocol (MCP)​

The MCP serves as the primary communication backbone for interactions involving AI models or agents. It allows different modules to expose their functionalities as "tools" that can be invoked by an AI model or an orchestrator. The model_context_protocol module defines the standards for these tool specifications and message formats.

Python APIs​

Modules also expose Python APIs for direct programmatic use by other modules or by external scripts and applications. These APIs are defined in each module's API_SPECIFICATION.md.

Shared Utility Modules​

  • logging_monitoring: Provides a standardized framework for logging across all modules.
  • environment_setup: Offers tools and guidance for setting up development and execution environments.
  • model_context_protocol: Defines the MCP itself, including schemas and validation logic.

Orchestration (Conceptual)​

While not a single, monolithic component, the concept of a "Core Orchestrator" represents the higher-level logic (which could be within an IDE extension, a central agent, or a user-driven script) that leverages MCP tools and Python APIs from various modules to achieve complex tasks.

Communication Flow​

  1. User/Agent Initiates Action: A user interacts with a Codomyrmex interface, or an AI agent decides to perform an action.
  2. MCP Invocation (if AI involved): If the action involves an AI-driven tool, an MCP request is formulated and sent to the relevant module that provides the tool.
  3. Python API Call (programmatic): For direct module-to-module interaction or scripting, Python functions from a module's API are called directly.
  4. Module Executes Logic: The target module processes the request, performs its operations (potentially interacting with other modules via their APIs), and utilizes shared services like logging.
  5. Response: The module returns a result, either as an MCP response or a Python return value.

Further Details​

For more in-depth information on specific modules, refer to their respective documentation sections available in the sidebar.

This high-level overview will be expanded as the project evolves.