# alumnium-hq/alumnium architecture

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

- Interactive diagram: https://gitdiagram.com/alumnium-hq/alumnium
- Repository: https://github.com/alumnium-hq/alumnium

## Overview

##### Main Components
- Alumni (Core Interface): This is the primary high-level interface (see alumni.py and the Alumni class in the README). It serves as the entry point where users call methods like “do”, “check”, and “get” to perform testing actions.
- Drivers Layer: Located in “alumnium/drivers”, this layer abstracts the actual browser drivers. There are implementations for Selenium and Playwright (plus scripts for supporting operations). This layer is responsible for interacting directly with the browser.
- Tools Layer: Found under “alumnium/tools”, these components (e.g., click_tool, drag_and_drop_tool, type_tool) encapsulate specific actions that streamline element interactions on web pages.
- Integration and Utility Modules: Additional files like alumni.py and aria.py act as orchestrators that tie the agents and drivers together, facilitating the overall test automation flow.

##### Relationships and Interactions
- The Client Code: Users write tests (as shown in the Quick Start section) which create an instance of Alumni. This instance then serves as the orchestrator.
- Command Flow: High-level test instructions are passed from the user code to the Alumni component. Alumni then leverages the appropriate Agent (actor, planner, or retriever) to parse and transform the instructions into actionable tasks.
- Action Execution: The Agents’ decisions are translated into operations provided by the Tools. These operations reach out to the Drivers, which interact with the actual browser.
- Data Flow & API Integration: Note the dependency on external services like OpenAI (indicated by the need for the “OPENAI_API_KEY”), suggesting that parts of the agents might use language models to interpret test commands.

##### Architectural Patterns and Design Principles
- Abstraction and Modularity: Different types of drivers and tools indicate the use of abstraction to support multiple interaction methods (i.e., Selenium vs. Playwright).
- Extensibility: The use of agents with prompt directories suggests that the system is designed to be extended with more behaviors and possibly further agent types.

##### Technologies and Frameworks
- AI and Language Processing: Likely integration with OpenAI’s API for natural language understanding.
- Test Automation: Use of Selenium, Playwright, and testing frameworks (pytest and behave) that interact with the underlying drivers.
- Python Ecosystem: The overall system is implemented in Python with a structured package (as evident from the pyproject.toml and Makefile).

- Integration: Clearly note the dependencies (e.g., environment variables like the API keys, and browser drivers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    User["User Test Script"]:::client

    %% Core Orchestration Layer
    Orchestrator["Alumni Orchestrator"]:::orchestrator
    IntegrationAria["Aria Module"]:::integration
    IntegrationModels["Models Module"]:::integration

    %% Agents Layer
    subgraph "Agents Layer"
        ActorAgent["Actor Agent"]:::agents
        PlannerAgent["Planner Agent"]:::agents
        RetrieverAgent["Retriever Agent"]:::agents
        ActorPrompts["Actor Prompts"]:::agents
        PlannerPrompts["Planner Prompts"]:::agents
        RetrieverPrompts["Retriever Prompts"]:::agents
        ActorAgent -->|"uses"| ActorPrompts
        PlannerAgent -->|"uses"| PlannerPrompts
        RetrieverAgent -->|"uses"| RetrieverPrompts
    end

    %% Tools Layer
    subgraph "Tools Layer"
        ClickTool["Click Tool"]:::tools
        DragTool["Drag-and-Drop Tool"]:::tools
        HoverTool["Hover Tool"]:::tools
        PressKeyTool["Press Key Tool"]:::tools
        SelectTool["Select Tool"]:::tools
        TypeTool["Type Tool"]:::tools
    end

    %% Drivers Layer
    subgraph "Drivers Layer"
        SeleniumDriver["Selenium Driver"]:::drivers
        PlaywrightDriver["Playwright Driver"]:::drivers
        DriverScripts["Drivers Scripts"]:::drivers
    end

    %% External Integration
    OpenAI["OpenAI_API"]:::external

    %% Examples and Tests
    Examples["Examples & Tests"]:::test

    %% Connections
    User -->|"submit"| Orchestrator
    Orchestrator -->|"orchestrates"| IntegrationAria
    Orchestrator -->|"orchestrates"| IntegrationModels
    Orchestrator -->|"delegatesTo"| ActorAgent
    Orchestrator -->|"delegatesTo"| PlannerAgent
    Orchestrator -->|"delegatesTo"| RetrieverAgent
    Orchestrator -->|"executes"| ClickTool
    Orchestrator -->|"executes"| DragTool
    Orchestrator -->|"executes"| HoverTool
    Orchestrator -->|"executes"| PressKeyTool
    Orchestrator -->|"executes"| SelectTool
    Orchestrator -->|"executes"| TypeTool
    ActorAgent -->|"queries"| OpenAI
    PlannerAgent -->|"queries"| OpenAI
    RetrieverAgent -->|"queries"| OpenAI
    ClickTool -->|"triggers"| SeleniumDriver
    ClickTool -->|"triggers"| PlaywrightDriver
    DragTool -->|"triggers"| SeleniumDriver
    DragTool -->|"triggers"| PlaywrightDriver
    HoverTool -->|"triggers"| SeleniumDriver
    HoverTool -->|"triggers"| PlaywrightDriver
    PressKeyTool -->|"triggers"| SeleniumDriver
    PressKeyTool -->|"triggers"| PlaywrightDriver
    SelectTool -->|"triggers"| SeleniumDriver
    SelectTool -->|"triggers"| PlaywrightDriver
    TypeTool -->|"triggers"| SeleniumDriver
    TypeTool -->|"triggers"| PlaywrightDriver
    SeleniumDriver -->|"usesScripts"| DriverScripts
    PlaywrightDriver -->|"usesScripts"| DriverScripts
    Examples -->|"validates"| Orchestrator

    %% Click Events for Component Mapping
    click Orchestrator "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/alumni.py"
    
    click ActorAgent "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/agents/actor_agent.py"
    click ActorPrompts "https://github.com/alumnium-hq/alumnium/tree/main/alumnium/agents/actor_prompts/"
    
    click PlannerAgent "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/agents/planner_agent.py"
    click PlannerPrompts "https://github.com/alumnium-hq/alumnium/tree/main/alumnium/agents/planner_prompts/"
    
    click RetrieverAgent "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/agents/retriever_agent.py"
    click RetrieverPrompts "https://github.com/alumnium-hq/alumnium/tree/main/alumnium/agents/retriever_prompts/"
    
    click SeleniumDriver "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/drivers/selenium_driver.py"
    click PlaywrightDriver "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/drivers/playwright_driver.py"
    click DriverScripts "https://github.com/alumnium-hq/alumnium/tree/main/alumnium/drivers/"
    
    click ClickTool "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/tools/click_tool.py"
    click DragTool "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/tools/drag_and_drop_tool.py"
    click HoverTool "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/tools/hover_tool.py"
    click PressKeyTool "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/tools/press_key_tool.py"
    click SelectTool "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/tools/select_tool.py"
    click TypeTool "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/tools/type_tool.py"
    
    click IntegrationAria "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/aria.py"
    click IntegrationModels "https://github.com/alumnium-hq/alumnium/blob/main/alumnium/models.py"
    
    click Examples "https://github.com/alumnium-hq/alumnium/tree/main/examples/"

    %% Styles
    classDef client fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef orchestrator fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef agents fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef tools fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef drivers fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef integration fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef test fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
```
