# matthewzmd/aidermacs architecture

> Architecture diagram of the GitHub repository matthewzmd/aidermacs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matthewzmd/aidermacs
- Repository: https://github.com/matthewzmd/aidermacs

## Overview

##### Main Components of the System
- User Interface Component:
– This includes the transient menu system (that resembles Magit) and prompt files minor mode.
- Core Functionality & Workflow Control:
– The core Emacs Lisp modules (e.g., aidermacs.el, aidermacs-models.el) that manage AI interactions.
– Submodules for file manipulation (adding, dropping files, session scratchpads) and command routing.
- Backend Integration Module:
– The backend support files (aidermacs-backend-comint.el, aidermacs-backend-vterm.el) that abstract the terminal interactions.
– This is where you differentiate the use of Emacs’ built-in comint versus vterm for terminal emulation.
- AI Model & Architect Mode Management:
– The modules and settings regarding dynamic model selection, Architect mode (with separate models for reasoning and code editing), and weak model configurations.
– Show model hashing logic (via aidermacs-models.el) and how the system chooses between editor/architect modes.
- Configuration & Extension Points:
– The module to read a custom configuration (via `.aider.conf.yml` file support and Emacs settings).
– Include the pre-run hook and extra arguments mechanism.
- External Dependencies:
– Illustrate the connection to external AI providers (OpenAI, Anthropic, DeepSeek, etc.) and mention that Aider handles API integrations.
– Denote integration points for external tools (e.g., dependencies set up via environment variables, assistance from Aider’s CLI program).

##### Relationships and Interactions
- Within Core Functionality, route control flows to:
o File Management (selecting files, read-only vs editable).
o Model & Mode Management (checking settings for Architect mode vs solo mode).
o Backend Integration (selecting comint vs vterm for terminal communication).
o Emacs settings (init.el, runtime variable overrides) and
o Project-specific configuration files (.aider.conf.yml).

##### Architectural Patterns and Design Principles
- Modular design: Each logical part (UI, core, backend, model management) is separated for clarity and maintainability.
- Configurability: The system respects both dynamic Emacs configuration and external config files that have precedence.
- Extensibility: The design allows adding new AI providers or backend modes without changing the core logic.
- Clear separation between user interactions (transient menu, keybindings) and backend processing (shell integrations and API calls).

##### Elements
- Clear labels for every component mentioned (UI, core logic, model management, backends, configuration, external API integration).
o From User Interface to Core Command Router,
o From Core to Model Management and to File Management subsystems,
o From Core to the external Aider backend and ultimately, the AI providers.
- Deployment/env boundaries such as “User’s Emacs” vs. “Aider API/External AI Providers”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    U("User (Emacs User)"):::external

    %% Configuration Loader (Emacs settings and .aider.conf.yml)
    CFG("Configuration Loader (.aider.conf.yml/init.el)"):::config

    %% Core Components
    UI("Transient Menu UI & Keybindings<br/>(e.g., C-c a, C-c C-n)"):::ui
    CORE("Core Command Router"):::core
    MODEL("AI Model Manager<br/>(Architect Mode & Model Selection)"):::model
    OUT("Output & Command Routing<br/>(Feedback / Ediff)"):::backend

    %% External Dependency
    EXT("Aider API/External AI Providers"):::external

    %% Backend Integration Subgraph
    subgraph "Backend Integration"
        COMINT("Terminal Backend (Comint)"):::backend
        VTERM("Terminal Backend (vterm)"):::backend
        AGG("Backend Aggregator"):::backend
    end

    %% Relationships
    U -->|"triggers"| UI
    UI -->|"delegates to"| CORE
    CFG -->|"supplies config to"| CORE
    CORE -->|"routes to"| MODEL
    CORE -->|"invokes"| COMINT
    CORE -->|"invokes"| VTERM
    CORE -->|"invokes"| AGG
    CORE -->|"handles output"| OUT
    CORE -->|"sends commands"| EXT
    OUT -->|"provides feedback"| U

    %% Click Events for Component Mapping
    click UI "https://github.com/matthewzmd/aidermacs/blob/main/aidermacs.el"
    click CORE "https://github.com/matthewzmd/aidermacs/blob/main/aidermacs.el"
    click MODEL "https://github.com/matthewzmd/aidermacs/blob/main/aidermacs-models.el"
    click COMINT "https://github.com/matthewzmd/aidermacs/blob/main/aidermacs-backend-comint.el"
    click VTERM "https://github.com/matthewzmd/aidermacs/blob/main/aidermacs-backend-vterm.el"
    click AGG "https://github.com/matthewzmd/aidermacs/blob/main/aidermacs-backends.el"
    click OUT "https://github.com/matthewzmd/aidermacs/blob/main/aidermacs-output.el"

    %% Styles
    classDef ui fill:#f9c,stroke:#333,stroke-width:2px,color:#000;
    classDef core fill:#9f9,stroke:#333,stroke-width:2px,color:#000;
    classDef model fill:#ff9,stroke:#333,stroke-width:2px,color:#000;
    classDef backend fill:#9ff,stroke:#333,stroke-width:2px,color:#000;
    classDef config fill:#fc9,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#f99,stroke:#333,stroke-width:2px,color:#000;
```
