# puravparab/waymo-api architecture

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

- Interactive diagram: https://gitdiagram.com/puravparab/waymo-api
- Repository: https://github.com/puravparab/waymo-api

## Overview

Below are the key steps and guidelines tailored to this project:

##### Main Components
- Client/Demo Components: The “examples” directory contains demonstration scripts (e.g., examples/demo/main.py, examples/sf/main.py) that show how to run single/multiple trip queries.
- API Core: Within the “src/waymo_api” directory, you have several submodules:
◦ “core” (client.py, driver.py, exceptions.py, models.py) – this layer encapsulates the fundamental API logic and communication routines.
◦ “interactions” (actions.py, extractor.py) – handles higher-level actions, possibly for initiating rides and extracting data.
◦ “utils” (logger.py) – provides logging functionality.
- External Dependencies and Infrastructure:
◦ Android Virtual Device (AVD) – running the Waymo One app.
◦ Appium server – enables interaction with the running Android emulator.
◦ Android debug bridge (adb) – used to change the device’s location.
◦ Setup tools such as Android Studio and npm for Appium installation.

##### Relationships and Interactions
- The demo examples call the Python API (client) which in turn interacts with the “core” and “interactions” modules.
- The “core” modules (client and driver) communicate with the Android emulator via Appium/adb.
- The API’s log messages, errors, and behavior are managed through the “utils/logger”.
- External flow: the emulator (running Waymo One) is set up with location modifications via adb and is controlled by the Appium server.
- The entire interaction pipeline connects user input, API command processing, and external device control.

##### Architectural Patterns and Technologies
- There is a clear separation between the API logic and external integration components.
- The structure follows a modular design where each module (core, interactions, utils) encapsulates specific responsibilities.
- Technologies in use: Python 3.12, uv package manager, Appium (Node-based), Android Studio/emulator, and adb.
- To note the “setup” steps in the README, highlighting the importance of ordering (first starting the AVD, then Appium).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client/Demo Scripts
    subgraph "Client/Demo Scripts"
        DS1("Demo Script"):::demo
        DS2("SF Script"):::demo
    end

    %% API Core Modules
    subgraph "API Core (Core Modules)"
        C1("client.py"):::core
        C2("driver.py"):::core
        C3("exceptions.py"):::core
        C4("models.py"):::core
    end

    %% API Interaction Modules
    subgraph "API Interactions"
        I1("actions.py"):::interaction
        I2("extractor.py"):::interaction
    end

    %% Logger Utility
    U("Logger Utility"):::utils

    %% External Dependencies
    subgraph "External Devices & Tools"
        E("Android Virtual Device (Waymo One)"):::external
        A("Appium Server"):::external
        D("adb for Geo Fix"):::external
    end

    %% Connections between components
    DS1 -->|"Calls"| C1
    DS2 -->|"Calls"| C1
    C1 -->|"Uses"| C2
    C1 -->|"Catches"| C3
    C1 -->|"WrapsData"| C4
    C1 -->|"Invokes"| I1
    C1 -->|"Invokes"| I2
    C1 -->|"LogsVia"| U
    C1 -->|"Commands"| A
    A -->|"Controls"| E
    D -->|"SetsLocation"| E

    %% Click Events for Component Mapping
    click DS1 "https://github.com/puravparab/waymo-api/blob/main/examples/demo/main.py"
    click DS2 "https://github.com/puravparab/waymo-api/blob/main/examples/sf/main.py"
    click C1 "https://github.com/puravparab/waymo-api/tree/main/src/waymo_api/core"
    click I1 "https://github.com/puravparab/waymo-api/tree/main/src/waymo_api/interactions"
    click I2 "https://github.com/puravparab/waymo-api/tree/main/src/waymo_api/interactions"
    click U "https://github.com/puravparab/waymo-api/blob/main/src/waymo_api/utils/logger.py"

    %% Styles
    classDef demo fill:#aqua,stroke:#333,stroke-width:2px;
    classDef core fill:#cfc,stroke:#333,stroke-width:2px;
    classDef interaction fill:#fc9,stroke:#333,stroke-width:2px;
    classDef utils fill:#ff9,stroke:#333,stroke-width:2px;
    classDef external fill:#f99,stroke:#333,stroke-width:2px;
```
