# uw-mad-dash/eva architecture

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

- Interactive diagram: https://gitdiagram.com/uw-mad-dash/eva
- Repository: https://github.com/uw-mad-dash/eva

## Overview

##### Main Components
- Global Storage: Represent the “Global Storage” element (Amazon S3) which holds the job artifacts. This component is accessed by both the master and workers.
- Master Node: This is the central controller that manages job submissions, scheduling, and cloud provisioning. Include submodules such as the scheduler, command, and job management (found in the master/ directory and associated RPC modules).
- Worker Nodes: These execute the jobs. They interact with global storage (using the storage_manager) and follow commands from the master.
- Cloud Provisioner: This component (under src/cloud_provisioner) interacts with AWS EC2 APIs to launch and shut down worker nodes based on resource demand.
- Experiment and Simulation Drivers: Represent the simulation components (e.g. simulation, simulator, experiment_driver_200.py, experiment_driver_full.py) that are used for evaluation of scheduling on both partial and full traces from Alibaba.
- Job Artifacts & Workloads: Represent the directory of job workloads (e.g. workloads/a3c, workloads/resnet18, etc.) which house the Dockerfiles and job-specific configurations used to containerize and execute the jobs.
- EVAIterator: This component (in the eva_iterator directory) that is embedded in user jobs in order to track throughput and interference; it communicates with the master/worker processes via RPC.

##### Relationships and Interactions
- For simulation experiments, illustrate that a separate driver component (simulation/ and simulator/) interacts with the scheduling logic to run trace-based experiments, generating cost metrics and performance reports.

##### Architectural Patterns and Design Principles
- The system follows a modular and layered design:
– Separation of Concerns: Cloud provisioning, scheduling, and actual job execution are clearly separated into different modules.
– RPC-based Communications: Many components communicate via defined RPC interfaces (see src/rpc and associated protobuf files).
– Containerized Workloads: Many workload directories include Dockerfiles, which indicates container-based job execution.
- Use of configuration files (e.g., eva_config.json, ec2_config.json, s3_config.json) that govern system behavior; these should be shown as configuration “settings” feeding into the Master Node and Cloud Provisioner.

##### Relevant Technologies and Frameworks
- AWS-specific components (EC2 for compute, S3 for storage).
- Containerization technology (Docker) used for workload execution.
- Reference Python-based execution and scheduling components.
- RPC mechanisms (often generated from protobuf definitions) that enable communication across modules.

##### Must-Have Elements
- Each component should have a clear label (for example “Master Node – Scheduling & Job Management”, “Worker Node – Execution”, “Cloud Provisioner – AWS EC2 APIs”, “Global Storage – Amazon S3”).
– Command flow from Master to Workers.
– Data flow from Global Storage to Worker Nodes and vice versa.
– Control flow from Cloud Provisioner to launching new Worker Nodes.
- Optionally, include configuration files as a supporting block that influences the operation of both the master (via eva_config.json, ec2_config.json) and provisioning components.

1. Job submission (via eva_submit.py or job_submission_driver.py)
2. Master scheduling and decision making
3. Worker node launching (via Cloud Provisioner)
4. Job artifact retrieval and container execution on the Worker
5. Synchronization back to Global Storage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure
    subgraph "Infrastructure"
        GS["Global Storage – Amazon S3"]:::storage
        CP["Cloud Provisioner – AWS EC2 APIs"]:::control
    end

    %% System Components
    subgraph "System Components"
        MN["Master Node – Scheduling & Job Management"]:::control
        ED["EVAIterator – Throughput Tracker"]:::iterator
        WD["Worker Node – Execution"]:::worker
        EX["Experiment Drivers – Simulation & Experiments"]:::experiment
        JA["Job Artifacts & Workloads"]:::artifact
    end

    %% Relationships
    MN -->|"dispatch"| WD
    MN <==>|"RPC"| WD
    CP -->|"launch/terminate"| WD
    WD -->|"download_artifacts"| GS
    WD -->|"upload_results"| GS
    GS -->|"sync_artifacts"| MN
    EX -->|"evaluate_scheduling"| MN
    ED -->|"RPC_integration"| WD
    ED -->|"reports_metrics"| MN
    WD -->|"retrieve_container"| JA

    %% Click Events
    click GS "https://github.com/uw-mad-dash/eva/blob/main/src/s3_config.json"
    click CP "https://github.com/uw-mad-dash/eva/blob/main/src/cloud_provisioner/ec2_provisioner.py"
    click MN "https://github.com/uw-mad-dash/eva/blob/main/src/master/master.py"
    click WD "https://github.com/uw-mad-dash/eva/blob/main/src/worker/worker.py"
    click ED "https://github.com/uw-mad-dash/eva/blob/main/src/eva_iterator/eva_iterator.py"
    click EX "https://github.com/uw-mad-dash/eva/blob/main/src/experiment_driver_200.py"
    click JA "https://github.com/uw-mad-dash/eva/tree/main/src/workloads/"

    %% Styles
    classDef control fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef storage fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef worker fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef experiment fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef artifact fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef iterator fill:#F5DEB3,stroke:#000,stroke-width:2px;
```
