# madbomber/aia architecture

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

- Interactive diagram: https://gitdiagram.com/madbomber/aia
- Repository: https://github.com/madbomber/aia

## Overview

##### Main Components
- CLI/Entry Point:
- The executable scripts in the “bin” directory (e.g., bin/aia, bin/console, bin/setup) define the entry points.
- The “justfile” and “main.just” indicate some scripting and task automation methods.
- Core Library:
- “lib/aia.rb” and the “lib/aia” subdirectory implement the core application logic.
- Look at files such as cli.rb, main.rb, config.rb, prompt.rb, logging.rb, and dynamic_content.rb – they represent the business logic, configuration management, and directive processing.
- Tool and Backend Integration:
- Under “lib/aia/tools” you find separate Ruby files for various external integrations (ai_client_backend.rb, client.rb, editor.rb, fzf.rb, glow.rb, llm.rb, mods.rb, sgpt.rb, etc.). These files encapsulate communication with different AI backends and external command-line tools.
- Directives and Dynamic Processing Subsystem:
- The system for managing prompt directives is spread through files like directives.rb and user_query.rb, indicating that the tool parses prompt files, substitutes shell commands and ERB templates, and then dispatches these prompts to backend AI processors.
- Testing and Documentation:

##### Relationships and Data Flow
- A client “User Interface” block that represents the command-line input.
- “Configuration Manager” (using files like configuration.yml, environment variable integration from .envrc, and configuration overrides via //config directives) as an independent module feeding configuration values into the rest of the system.
- A “Prompt Manager” component that handles loading prompt files, processing directives (//config, //include, //ruby, //shell), and inserting dynamic content (ERB, shell substitution). Indicate that it interacts with “Roles” and “Prompt Sequences”.

##### Architectural Patterns & Design Principles
- Modularity: The system is segmented into distinct directories for CLI, core logic, backend tools, and tests.
- Separation of Concerns: There is a clear separation between prompt processing, configuration management, and AI backend interactions.
- Extensibility: The design (e.g., support for plugins via “roles” and dynamic directive parsing) allows the easy addition of new prompt directives or backend processors.
- Integration with External Tools: Notice how external programs (fzf, ripgrep, etc.) are integrated to support user interaction and file search.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontend
    subgraph "CLI Frontend"
        CLI_AIA["CLI Entry: bin/aia"]:::cli
        CLI_CONSOLE["CLI Entry: bin/console"]:::cli
        CLI_SETUP["CLI Entry: bin/setup"]:::cli
        JUSTFILE["Task Automation: justfile"]:::cli
        MAINJUST["Task Automation: main.just"]:::cli
    end

    %% Core Processing
    subgraph "Core Processing"
        CMD["Command Parser & Dispatcher<br/>(lib/aia/cli.rb)"]:::core
        CORELIB["Core Library<br/>(lib/aia.rb, lib/aia)"]:::core
        CONFIG_RUBY["Configuration Manager<br/>(lib/aia/config.rb)"]:::core
        CONFIG_YML["Configuration Overrides<br/>(.config/tocer/configuration.yml)"]:::core
        PROMPT["Prompt & Directive Processor<br/>(lib/aia/prompt.rb, directives.rb, dynamic_content.rb)"]:::core
        LOGGING["Logging<br/>(lib/aia/logging.rb)"]:::core
        USERQUERY["User Query Handling<br/>(lib/aia/user_query.rb)"]:::core
    end

    %% External Integration
    subgraph "External Integration"
        AI_CLIENT["AI Client & Backend Adapter<br/>(lib/aia/tools)"]:::backend
        EXTERNAL_TOOLS["External CLI Tools<br/>(fzf, ripgrep, glow, sgpt, mods)"]:::external
    end

    %% QA & Documentation
    subgraph "QA & Documentation"
        DOC["Documentation<br/>(doc, man/aia.1, man/aia.1.md)"]:::qa
        TEST["Testing Framework<br/>(test)"]:::qa
    end

    %% Connections from CLI Frontend to Core Processing
    CLI_AIA --> CLI_CONSOLE
    CLI_AIA --> CMD
    CLI_CONSOLE --> CMD
    CLI_SETUP --> CMD
    JUSTFILE --> CMD
    MAINJUST --> CMD

    %% Core Processing internal flow
    CMD -->|"parse"| CORELIB
    CMD -->|"dispatch"| CONFIG_RUBY
    CMD -->|"trigger"| PROMPT
    CMD --> LOGGING
    CONFIG_RUBY -->|"configure"| PROMPT
    CONFIG_YML -->|"override"| PROMPT
    PROMPT --> USERQUERY
    PROMPT -->|"calls"| AI_CLIENT

    %% External Integration flow
    AI_CLIENT -->|"integrates"| EXTERNAL_TOOLS
    AI_CLIENT -->|"response"| CLI_AIA

    %% Styling Classes
    classDef cli fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#333,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#333,stroke-width:2px;
    classDef qa fill:#F5B7B1,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI_AIA "https://github.com/madbomber/aia/tree/main/bin/aia"
    click CLI_CONSOLE "https://github.com/madbomber/aia/tree/main/bin/console"
    click CLI_SETUP "https://github.com/madbomber/aia/tree/main/bin/setup"
    click JUSTFILE "https://github.com/madbomber/aia/tree/main/justfile"
    click MAINJUST "https://github.com/madbomber/aia/blob/main/main.just"
    click CMD "https://github.com/madbomber/aia/blob/main/lib/aia/cli.rb"
    click CORELIB "https://github.com/madbomber/aia/tree/main/lib/aia"
    click CONFIG_RUBY "https://github.com/madbomber/aia/blob/main/lib/aia/config.rb"
    click CONFIG_YML "https://github.com/madbomber/aia/blob/main/.config/tocer/configuration.yml"
    click PROMPT "https://github.com/madbomber/aia/blob/main/lib/aia/prompt.rb"
    click LOGGING "https://github.com/madbomber/aia/blob/main/lib/aia/logging.rb"
    click USERQUERY "https://github.com/madbomber/aia/blob/main/lib/aia/user_query.rb"
    click AI_CLIENT "https://github.com/madbomber/aia/tree/main/lib/aia/tools"
    click DOC "https://github.com/madbomber/aia/tree/main/doc"
    click TEST "https://github.com/madbomber/aia/tree/main/test"
```
