# neuhai/uxagent architecture

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

- Interactive diagram: https://gitdiagram.com/neuhai/uxagent
- Repository: https://github.com/neuhai/uxagent

## Overview

##### Project type and purpose
- UXAgent is a Python-based framework that uses LLMs as autonomous agents to conduct web usability tests.
- It simulates user personas against any web page via a “Universal Web Connector,” collecting feedback and design insights automatically.

##### File structure
- Top-level: configuration (`environment.yml`, `pyproject.toml`), persona data (`example_data/personas`), figures.
- `src/simulated_web_agent`: the core package.
- `agent/`: LLM orchestration—context management, memory, prompt templates, GPT wrapper.
- `executor/`: web‐driving layer—Selenium/Chromedriver environment setup (`env.py`) plus site‐specific “recipes” for actions (e.g., `amazon_recipes.py`).
- `main/`: CLI entrypoints (`__main__.py`), persona generation (`persona.py`), experiment replay (`replay.py`), model definitions.

##### README for additional insights
- Dual-system reasoning: quick decisions (System 1) vs. in-depth analysis (System 2).
- Universal Web Connector: adapter to drive any web UI via Selenium.
- Supports OpenAI/AWS Claude as LLM backends.
- Personas stored as JSON/TXT; used to parameterize agent behavior.

##### Detail
- Sub-components: Prompt Library, Memory Store, site recipes.
- Sense-plan-act loop clearly.
- Don’t omit the Universal Web Connector as a key adapter layer.
- Optional headful vs. headless mode via an environment flag.
- Dependencies: `environment.yml`, `pyproject.toml`, `chromedriver`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        PersonaData["Persona Data Store"]:::data
    end

    subgraph "CLI & Orchestrator"
        Orchestrator["CLI Orchestrator"]:::orchestrator
        PersonaLoader["Persona Loader"]:::orchestrator
        ModelDef["Model Definitions"]:::orchestrator
        Replay["Experiment Replay / Output"]:::data
    end

    subgraph "Agent Engine"
        Agent["Agent Engine – Orchestration"]:::agent
        Context["Context Management"]:::agent
        Memory["Memory Module"]:::agent
        GPT["LLM Interface (GPT Wrapper)"]:::agent
        PromptsFlight["Prompt Library (Flight)"]:::agent
        PromptsShop["Prompt Library (Shopping)"]:::agent
    end

    subgraph "Executor Engine"
        Env["Universal Web Connector Setup"]:::executor
        RecipeAmazon["Site-specific Recipes (Amazon)"]:::executor
        RecipeFlights["Site-specific Recipes (Google Flights)"]:::executor
        RecipeOneStop["Site-specific Recipes (OneStopShop)"]:::executor
    end

    subgraph "External LLM Service"
        LLM["External LLM Service (OpenAI / AWS Claude)"]:::external
    end

    PersonaData -->|"persona config"| Orchestrator
    Orchestrator -->|"load persona"| PersonaLoader
    PersonaLoader -->|"persona object"| Agent
    Orchestrator -->|"invoke experiment"| Agent
    ModelDef -->|"model settings"| Agent

    Agent -->|"pull prompts"| PromptsFlight
    Agent -->|"pull prompts"| PromptsShop
    PromptsFlight --> Agent
    PromptsShop --> Agent

    Agent -->|"update context"| Context
    Agent -->|"read/write memory"| Memory

    Agent -->|"LLM request"| GPT
    GPT -->|"API call"| LLM
    LLM -->|"LLM response"| GPT
    GPT -->|"LLM response"| Agent

    Agent -->|"action plan"| Env
    Env -->|"configure browser (headful/headless)"| RecipeAmazon
    Env -->|"configure browser (headful/headless)"| RecipeFlights
    Env -->|"configure browser (headful/headless)"| RecipeOneStop

    RecipeAmazon -->|"page observations"| Agent
    RecipeFlights -->|"page observations"| Agent
    RecipeOneStop -->|"page observations"| Agent

    Agent -->|"final report"| Replay

    click Orchestrator "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/main/__main__.py"
    click PersonaLoader "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/main/persona.py"
    click Replay "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/main/replay.py"
    click ModelDef "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/main/model.py"
    click Agent "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/agent/agent.py"
    click Context "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/agent/context.py"
    click Memory "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/agent/memory.py"
    click GPT "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/agent/gpt.py"
    click PromptsFlight "https://github.com/neuhai/uxagent/tree/master/src/simulated_web_agent/agent/flight_prompts/"
    click PromptsShop "https://github.com/neuhai/uxagent/tree/master/src/simulated_web_agent/agent/shop_prompts/"
    click Env "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/executor/env.py"
    click RecipeAmazon "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/executor/amazon_recipes.py"
    click RecipeFlights "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/executor/google_flights_recipes.py"
    click RecipeOneStop "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/executor/onestopshop_recipes.py"
    click PersonaData "https://github.com/neuhai/uxagent/tree/master/example_data/personas"
    click Replay "https://github.com/neuhai/uxagent/blob/master/src/simulated_web_agent/main/replay.py"

    classDef orchestrator fill:#cce5ff,stroke:#004085,color:#004085
    classDef agent fill:#cce5ff,stroke:#004085,color:#004085
    classDef executor fill:#d4edda,stroke:#155724,color:#155724
    classDef data fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#bfc0c1,color:#6c757d
```
