# collinq/agent-eval architecture

> Architecture diagram of the GitHub repository collinq/agent-eval, 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/collinq/agent-eval
- Repository: https://github.com/collinq/agent-eval

## Overview

##### Frontend – A React/TypeScript application
- Located in the "frontend" directory.
- Contains pages (e.g., Home, Challenge, Leaderboard, Profile) and various components.
- Uses services and a store to handle API calls and authentication.
- Built with modern tooling (Vite, Tailwind CSS) to manage the UI.
- This layer is where users interact with the application, perform uploads, and view benchmark scores.

##### Backend – A Node.js/Express server
- Located in the "backend" directory.
- Organized using an MVC-like structure with separate folders for models, controllers, and routes.
- Handles requests coming from the frontend; routes for agents, challenges, and evaluations.
- Contains configuration files (e.g., “config/database.js”) indicating database connectivity and overall application configuration.
- Acts as the central API and orchestration point for business logic.

##### Web Arena Service – A Python-based component
- Located in the "webarena_service" directory.
- Contains a Python application (e.g., "app.py", "fixed_webarena_test.py") along with other scripts (some marked as UNUSED, which might be legacy or experimental code).
- Likely responsible for the actual evaluation and benchmarking of the uploaded agents using WebArena.
- The presence of "requirements.txt" confirms its dependency management with Python packages.

- Frontend Client (React App):
– Include subcomponents such as Pages, Components, and API Service.
- API Backend Server (Node.js/Express):
– Show it as a central service handling endpoints.
– Include indicators of the MVC structure: Controllers, Models, Routes.
– Mark key endpoints for Agents, Challenges, and Evaluations.
- Python WebArena Service:
– Represent this as a separate service that runs the evaluation logic.
– Label it clearly to denote its responsibility in evaluating the agents.

B. Determine Component Interactions:
- Communication between the Backend and the WebArena Service. For example, when an agent is to be evaluated, the backend invokes the Python service and then forwards the results back to the frontend.
- Data flows such as:
- User uploads agent data via the Frontend.
- Frontend sends agent data or requests to the Backend.
- Backend processes the information (using controllers/models) and, if required, calls the WebArena Service for evaluation.
- Evaluation feedback flows back through the Backend to be rendered by the Frontend.

C. Note Relevant Architectural Patterns and Technologies:
- Separation of Concerns: The clear split into Frontend, Backend, and a specialized Python service aligns with the single-responsibility principle.
- MVC Pattern in the Backend: Controllers, Models, and Routes manage the logic for agents, challenges, and evaluations.
- API Gateway Pattern (Implicit): The Backend acts as the middle layer that abstracts the complexities of the Python evaluation service from the frontend.
- Use of modern frameworks and tools: Express for the Node.js server; React + Vite for the Frontend; Python for specialized tasks.

- Because this is a benchmark platform for web browsing agents, emphasize:
- The split of user interface (frontend) and business logic (backend) layers.
- The integration with the Python-based evaluation service (key to the project’s purpose).
- Each critical component’s role in handling upload, evaluation, and results display.
- Incorporate details such as:
- API endpoints and the main controllers involved in handling Agents, Challenges, and Evaluations.
- The “database” element if applicable (even if not explicitly detailed, it can be represented as a persistence layer given the "database.js" configuration).
- Noting external dependencies like WebArena (which might be used or extended by the Python service).

- Use names like “Frontend (React)”, “Backend (Express/MVC)”, “Python WebArena Service”, and optionally “Database” if needed.
- API requests from Frontend to Backend.
- Calls from Backend to Python service for initiating evaluations.
4. Integration flows:
- Where the user commands are transformed into evaluation tasks and how data flows back from the WebArena service to the user.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer (React Client)
    subgraph "Frontend (React Client)"
        FE["Frontend (React)"]:::frontend
        subgraph "Pages"
            FE_P1["Home.tsx"]:::page
            FE_P2["Challenge.tsx"]:::page
            FE_P3["Leaderboard.tsx"]:::page
            FE_P4["Profile.tsx"]:::page
        end
        subgraph "Components"
            FE_C1["AgentSelector.tsx"]:::component
            FE_C2["Layout.tsx"]:::component
            FE_C3["ProtectedRoute.tsx"]:::component
        end
        FE_API["API Service"]:::service
        FE_STORE["State/Store"]:::store
    end

    %% Backend Layer (Node.js/Express)
    subgraph "Backend (Express/MVC)"
        BE["Backend (Express)"]:::backend
        BE_ENTRY["app.js"]:::entry
        BE_CONFIG["database.js"]:::config
        subgraph "Controllers"
            BE_CTRL1["agentsController.js"]:::controller
            BE_CTRL2["challengesController.js"]:::controller
            BE_CTRL3["evaluationController.js"]:::controller
        end
        subgraph "Models"
            BE_MODEL1["Agent.js"]:::model
            BE_MODEL2["Challenge.js"]:::model
            BE_MODEL3["Evaluation.js"]:::model
        end
        subgraph "Routes"
            BE_ROUTE1["agents.js"]:::route
            BE_ROUTE2["challenges.js"]:::route
            BE_ROUTE3["evaluations.js"]:::route
            BE_ROUTE4["index.js"]:::route
        end
    end

    %% Python WebArena Service
    subgraph "Python WebArena Service"
        PY["Python WebArena Service"]:::python
        PY_APP["app.py"]:::pyApp
        PY_TEST["fixed_webarena_test.py"]:::pyTest
        PY_TEST_AGENT["test_agent.py"]:::pyTest
        PY_REQ["requirements.txt"]:::dep
        subgraph "Legacy/Unused"
            PY_LEGACY1["UNUSED_debug_webarena.py"]:::legacy
            PY_LEGACY2["UNUSED_my_agent.py"]:::legacy
            PY_LEGACY3["UNUSED_print_obs_tree.py"]:::legacy
            PY_LEGACY4["UNUSED_send_email_agent.py"]:::legacy
            PY_LEGACY5["UNUSED_test_webarena.py"]:::legacy
        end
    end

    %% Connections
    FE -->|"API_requests"| BE
    FE_API -->|"calls"| BE
    BE -->|"triggers_evaluation"| PY
    PY -->|"returns_results"| BE
    BE -->|"sends_responses"| FE

    %% Click Events for Frontend components
    click FE_P1 "https://github.com/collinq/agent-eval/blob/main/frontend/src/pages/Home.tsx"
    click FE_P2 "https://github.com/collinq/agent-eval/blob/main/frontend/src/pages/Challenge.tsx"
    click FE_P3 "https://github.com/collinq/agent-eval/blob/main/frontend/src/pages/Leaderboard.tsx"
    click FE_P4 "https://github.com/collinq/agent-eval/blob/main/frontend/src/pages/Profile.tsx"
    click FE_C1 "https://github.com/collinq/agent-eval/blob/main/frontend/src/components/AgentSelector.tsx"
    click FE_C2 "https://github.com/collinq/agent-eval/blob/main/frontend/src/components/Layout.tsx"
    click FE_C3 "https://github.com/collinq/agent-eval/blob/main/frontend/src/components/ProtectedRoute.tsx"
    click FE_API "https://github.com/collinq/agent-eval/blob/main/frontend/src/services/api.ts"
    click FE_STORE "https://github.com/collinq/agent-eval/blob/main/frontend/src/store/auth.ts"

    %% Click Events for Backend components
    click BE_ENTRY "https://github.com/collinq/agent-eval/blob/main/backend/app.js"
    click BE_CONFIG "https://github.com/collinq/agent-eval/blob/main/backend/config/database.js"
    click BE_CTRL1 "https://github.com/collinq/agent-eval/blob/main/backend/controllers/agentsController.js"
    click BE_CTRL2 "https://github.com/collinq/agent-eval/blob/main/backend/controllers/challengesController.js"
    click BE_CTRL3 "https://github.com/collinq/agent-eval/blob/main/backend/controllers/evaluationController.js"
    click BE_MODEL1 "https://github.com/collinq/agent-eval/blob/main/backend/models/Agent.js"
    click BE_MODEL2 "https://github.com/collinq/agent-eval/blob/main/backend/models/Challenge.js"
    click BE_MODEL3 "https://github.com/collinq/agent-eval/blob/main/backend/models/Evaluation.js"
    click BE_ROUTE1 "https://github.com/collinq/agent-eval/blob/main/backend/routes/agents.js"
    click BE_ROUTE2 "https://github.com/collinq/agent-eval/blob/main/backend/routes/challenges.js"
    click BE_ROUTE3 "https://github.com/collinq/agent-eval/blob/main/backend/routes/evaluations.js"
    click BE_ROUTE4 "https://github.com/collinq/agent-eval/blob/main/backend/routes/index.js"

    %% Click Events for Python WebArena Service components
    click PY_APP "https://github.com/collinq/agent-eval/blob/main/webarena_service/app.py"
    click PY_TEST "https://github.com/collinq/agent-eval/blob/main/webarena_service/fixed_webarena_test.py"
    click PY_TEST_AGENT "https://github.com/collinq/agent-eval/blob/main/webarena_service/test_agent.py"
    click PY_REQ "https://github.com/collinq/agent-eval/blob/main/webarena_service/requirements.txt"
    click PY_LEGACY1 "https://github.com/collinq/agent-eval/blob/main/webarena_service/UNUSED_debug_webarena.py"
    click PY_LEGACY2 "https://github.com/collinq/agent-eval/blob/main/webarena_service/UNUSED_my_agent.py"
    click PY_LEGACY3 "https://github.com/collinq/agent-eval/blob/main/webarena_service/UNUSED_print_obs_tree.py"
    click PY_LEGACY4 "https://github.com/collinq/agent-eval/blob/main/webarena_service/UNUSED_send_email_agent.py"
    click PY_LEGACY5 "https://github.com/collinq/agent-eval/blob/main/webarena_service/UNUSED_test_webarena.py"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
    classDef page fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef component fill:#fff2cc,stroke:#b45f06,stroke-width:2px;
    classDef service fill:#f9cb9c,stroke:#e69138,stroke-width:2px;
    classDef store fill:#ead1dc,stroke:#a64d79,stroke-width:2px;
    classDef backend fill:#d0e0e3,stroke:#1155cc,stroke-width:2px;
    classDef entry fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
    classDef config fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
    classDef controller fill:#ead1dc,stroke:#a64d79,stroke-width:2px;
    classDef model fill:#ffffff,stroke:#cccccc,stroke-width:2px;
    classDef route fill:#fce5cd,stroke:#e69138,stroke-width:2px;
    classDef python fill:#d9d2e9,stroke:#8e7cc3,stroke-width:2px;
    classDef pyApp fill:#d9d2e9,stroke:#8e7cc3,stroke-width:2px;
    classDef pyTest fill:#ead1dc,stroke:#a64d79,stroke-width:2px;
    classDef legacy fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
    classDef dep fill:#d0e0e3,stroke:#1155cc,stroke-width:2px;
```
