# Codomyrmex Architecture

## Overview

Codomyrmex is designed as a modular, extensible coding workspace that integrates various tools for building, documenting, analyzing, executing, and visualizing code. The architecture follows a layered, modular approach with clear separation of concerns.

## Core Architectural Principles

### 1. Modularity First

- Each module is self-contained with its own dependencies, tests, and documentation
- Modules can be used independently or in combination
- Clear interfaces between modules using defined APIs

### 2. Separation of Tool vs. Content

- **Tools** (like documentation generation) are separate from **content** (like project documentation)
- Codomyrmex tools don't "leave a mark" on the projects they analyze
- Clear boundaries between what Codomyrmex provides vs. what it generates

### 3. Polyglot Support

- Support for multiple programming languages and frameworks
- Language-agnostic interfaces where possible
- Pluggable language-specific implementations

### 4. AI Integration

- Designed for seamless integration with Large Language Models (LLMs)
- Model Context Protocol (MCP) for standardized AI communication
- AI-enhanced workflows without vendor lock-in

## System Architecture

```mermaid
graph TB
    subgraph sg_6c79c72ff1 [User Interfaces]
        CLI["CLI<br/>(codomyrmex)"]
        Shell["Interactive<br/>Shell"]
        API["API Endpoints<br/>(FastAPI)"]
    end

    subgraph sg_8c861d1c94 [Core Services Layer]
        Discovery["System<br/>Discovery"]
        Status["Status<br/>Reporting"]
        Terminal["Interactive<br/>Terminal"]
    end

    subgraph sg_5023f964c6 [Module Layer - AI & Intelligence]
        AICode["AI Code<br/>Editing"]
        MCP["Model Context<br/>Protocol"]
    end

    subgraph sg_d8702d52e6 [Module Layer - Analysis & Quality]
        CodeExec["Coding<br/>(static_analysis, pattern_matching)"]
    end

    subgraph sg_4e319ce7ac [Module Layer - Build & Deploy]
        CICD["CI/CD Automation<br/>(includes build)"]
        Git["Git<br/>Operations"]
        Docs["Documentation<br/>Generation"]
    end

    subgraph sg_cb4190d5bb [Module Layer - Visualization]
        DataViz["Data<br/>Visualization"]
    end

    subgraph sg_5f13f7c061 [Foundation Layer]
        Logging["Logging &<br/>Monitoring"]
        Environment["Environment<br/>Setup"]
        TerminalInterface["Terminal<br/>Interface"]
    end

    %% User Interface connections
    CLI --> Discovery
    Shell --> Terminal
    API --> Status

    %% Service Layer connections
    Discovery --> AICode
    Discovery --> CodeExec
    Status --> DataViz
    Terminal --> Shell

    %% Module interconnections
    AICode --> CodeExec
    AICode --> MCP
    CodeExec --> CICD
    CICD --> Git
    CICD --> Docs

    %% Foundation connections
    AICode --> Logging
    CodeExec --> Logging
    DataViz --> Logging
    CICD --> Logging
    Git --> Logging
    Docs --> Logging

    Environment --> AICode
    Environment --> CodeExec

    TerminalInterface --> Terminal
    TerminalInterface --> CLI
```

### **System Layer Interactions**

The Codomyrmex architecture follows a **layered approach** with clear separation between:

- **User Interfaces**: How users interact with the system
- **Core Services**: System-level services and orchestration
- **Module Layer**: Functional modules organized by domain
- **Foundation Layer**: Infrastructure services used by all modules

**Related Documentation**:

- **[Module Overview](../modules/overview.md)**: Detailed module architecture
- **[Module Relationships](../modules/relationships.md)**: Inter-module dependencies
- **[API Reference](../reference/api.md)**: Complete API documentation

## Module Categories

### Foundation Modules

**Purpose**: Core infrastructure used by all other modules

- **`logging_monitoring`**: Centralized logging system
- **`environment_setup`**: Environment validation and configuration
- **`terminal_interface`**: Rich terminal interactions and formatting
- **`config_management`**: Centralized configuration management
- **`database_management`**: Data persistence and database operations
- **`llm`**: LLM infrastructure and provider abstraction
- **`performance`**: Performance monitoring and optimization

### Core Functional Modules

**Purpose**: Primary capabilities that users directly interact with

- **`agents`**: AI-powered code generation and modification
- **`coding`**: Safe code execution environment (includes `static_analysis/` and `pattern_matching/` sub-modules)
- **`data_visualization`**: Chart and plot generation
- **`git_operations`**: Git workflow automation
- **`security`**: Security vulnerability scanning and compliance
- **`llm/ollama`**: Local LLM integration via Ollama

### Service Modules

**Purpose**: Higher-level services that orchestrate core modules

- **`documentation`**: Documentation website generation
- **`ci_cd_automation`**: CI/CD pipeline management, build automation, and deployment (includes `build/` sub-module)
- **`containerization`**: Docker and Kubernetes container management

### Integration Modules

**Purpose**: Standards and protocols for system integration

- **`model_context_protocol`**: Standardized AI/LLM communication
- **`module_template`**: Template for creating new modules

### Application Modules

**Purpose**: User-facing applications and interfaces

- **`system_discovery`**: Module and capability discovery
- **`orchestrator`**: Workflow orchestration and task management
- **`cli`**: Command-line interface for all modules

### Advanced Modules

**Purpose**: Specialized capabilities for advanced use cases

- **`spatial`**: 3D modeling and visualization
- **`physical_management`**: Physical system simulation and management

### Secure Cognitive Modules

**Purpose**: Autonomous security and economic capabilities

- **`identity`**: 3-Tier persona management and verification
- **`wallet`**: Self-custody wallet and ritual recovery
- **`defense`**: Active defense and exploit containment
- **`market`**: Anonymous economic coordination
- **`privacy`**: Mixnet routing and data sanitization

## Data Flow Patterns

### 1. Discovery and Analysis Flow

```
User Request → System Discovery → Module Analysis → Capability Mapping → Results
```

### 2. AI-Enhanced Development Flow

```
Code Input → Pattern Analysis → AI Processing → Code Generation → Validation → Output
```

### 3. Quality Assurance Flow

```
Source Code → Static Analysis → Testing → Build Validation → Deployment
```

## Key Design Decisions

### Documentation Architecture

- **Top-level `docs/`**: Documentation about Codomyrmex itself
- **`src/codomyrmex/documentation/`**: Tool for generating documentation for other projects
- **Module `docs/`**: Documentation specific to each module

### Dependency Management

- **`pyproject.toml`**: All dependencies managed centrally with optional extras per module
- **`uv.lock`**: Lockfile for reproducible environments
- **Version pinning**: Managed through uv lockfile for reproducibility

### Configuration Strategy

- **Environment variables**: For runtime configuration and API keys
- **`.env` files**: For local development configuration
- **Module configs**: For module-specific settings

### Testing Strategy

- **Unit tests**: In `src/codomyrmex/tests/unit/` for individual module testing
- **Integration tests**: In `src/codomyrmex/tests/integration/` for cross-module workflows
- **Comprehensive coverage**: Target >80% coverage across all modules

## Extension Points

### Adding New Modules

1. Use the `module_template` as a starting point
2. Follow the established directory structure
3. Implement standard interfaces (`API_SPECIFICATION.md`, `MCP_TOOL_SPECIFICATION.md`)
4. Add comprehensive tests and documentation

### AI Integration

- Implement MCP protocol for LLM communication
- Use standard prompt templates and response formats
- Support multiple AI providers (OpenAI, Anthropic, Google, etc.)

### Language Support

- Extend existing modules to support new languages
- Add language-specific analysis tools
- Implement language-specific code execution environments

## Security Considerations

### Code Execution

- All code execution happens in sandboxed environments
- Network access restrictions for untrusted code
- Resource limits (CPU, memory, time) for all executions

### API Keys and Secrets

- Never commit secrets to version control
- Use environment variables for sensitive configuration
- Validate and sanitize all external inputs

### Static Analysis

- Security-focused linting with `bandit` and other tools
- Regular dependency vulnerability scanning
- Input validation for all user-provided data

## Performance Considerations

### Module Loading

- Lazy loading of modules to reduce startup time
- Cached module discovery to avoid repeated filesystem scans
- Optional dependencies that don't block core functionality

### Concurrent Operations

- Parallel module analysis where possible
- Asynchronous I/O for external service calls
- Progress reporting for long-running operations

### Resource Management

- Memory-efficient processing of large codebases
- Streaming data processing where applicable
- Cleanup of temporary files and resources

## 🔗 Related Documentation

### **Deep Dive Topics**

- **[Module System Overview](../modules/overview.md)**: Detailed module architecture and principles
- **[Module Relationships](../modules/relationships.md)**: Inter-module dependencies and data flow
- **[API Reference](../reference/api.md)**: Complete API documentation for all modules
- **[CLI Reference](../reference/cli.md)**: Command-line interface documentation

### **Development Resources**

- **[Contributing Guide](./contributing.md)**: How to contribute to the architecture
- **[Development Setup](../development/environment-setup.md)**: Setting up development environment
- **[Documentation Guidelines](../development/documentation.md)**: Maintaining architectural documentation
- **[Module Creation Tutorial](../getting-started/tutorials/creating-a-module.md)**: Building new modules

### **User Guides**

- **[Installation Guide](../getting-started/installation.md)**: System requirements and setup
- **[Quick Start Guide](../getting-started/quickstart.md)**: Getting started with the architecture
- **[Troubleshooting Guide](../reference/troubleshooting.md)**: Common architecture-related issues

### **Source Code Navigation**

- **[Source Overview](../../README.md)**: Source code organization
- **[Package Overview](../../src/codomyrmex/README.md)**: Main package structure
- **[Module Template](../../src/codomyrmex/module_template/README.md)**: Template for new modules

### **Orchestration and Coordination**

- **[Task Orchestration Guide](../project_orchestration/task-orchestration-guide.md)**: Complete task orchestration guide
- **[Project Lifecycle Guide](../project_orchestration/project-lifecycle-guide.md)**: Project management lifecycle
- **[Dispatch and Coordination](../project_orchestration/dispatch-coordination.md)**: Task and workflow dispatch patterns
- **[Config-Driven Operations](../project_orchestration/config-driven-operations.md)**: Configuration-driven workflows
- **[Workflow Configuration Schema](../project_orchestration/workflow-configuration-schema.md)**: Workflow JSON schema
- **[Project Template Schema](../project_orchestration/project-template-schema.md)**: Project template structure
- **[Resource Configuration](../project_orchestration/resource-configuration.md)**: Resource management

---

This architecture provides a solid foundation for extensible, maintainable code analysis and development workflow automation while maintaining clear separation of concerns and supporting diverse use cases.

**Next Steps:**

1. **Explore Modules**: Review the [Module System Overview](../modules/overview.md)
2. **Try It Out**: Follow the [Quick Start Guide](../getting-started/quickstart.md)
3. **Get Involved**: Read the [Contributing Guide](./contributing.md)
4. **Learn Orchestration**: Review the [Task Orchestration Guide](../project_orchestration/task-orchestration-guide.md)

## Navigation Links

- **Parent**: [Project Overview](../README.md)
- **Module Index**: [All Agents](../../AGENTS.md)
- **Documentation**: [Reference Guides](../../docs/README.md)
- **Home**: [Repository Root](../../README.md)
