# google-agentic-commerce/ap2 architecture

> Architecture diagram of the GitHub repository google-agentic-commerce/ap2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-agentic-commerce/ap2
- Repository: https://github.com/google-agentic-commerce/ap2

## Overview

##### Project type and purpose
- This is an open-source protocol implementation and demonstration repository for the Agent Payments Protocol (AP2).
- It provides:
- A Python “types” package defining the core AP2 objects (in src/ap2/types).
- A set of Python microservices (under samples/python) that run various agent roles (shopping agent, merchant agent, credentials provider, payment processor) using ADK and Gemini LLM.
- An Android sample app (under samples/android/shopping_assistant) showing a shopping assistant UI that interacts with Python agents via A2A messaging.
- Documentation and scenario scripts demonstrating how to run end-to-end flows.

##### File structure
- Top-level directories:
- src/ap2/types – protocol object definitions (future PyPI package).
- samples/python – Python scenarios, common utilities, and role-based microservices.
- samples/android – Android demo app structured with Gradle, Jetpack Compose MVVM.
- docs and mkdocs.yml – site documentation for protocol spec, glossary, FAQs.
- .github, pipelines, lint configs – CI/CD, linting, release automation.
- Patterns and configurations:
- Python services share a common library (samples/python/src/common) for A2A message building, HTTP server logic, retry utilities, log watching.
- Each “role” is a standalone Python process (entrypoint __main__.py) that loads agent.json to configure tools and LLM calls.
- Android app is a Compose-based UI with ChatViewModel, A2AClient, repository, and data model layers.
- run.sh scripts orchestrate dependency installation and startup of multiple agents.

##### README for additional insights
- The README states this is purely a samples repo using ADK & Gemini 2.5 but not requiring them.
- It directs you to scenario readmes and run.sh to launch agents.
- It highlights that src/ap2/types is the protocol’s core object definitions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Shared Libraries
    subgraph "Shared Libraries"
        Types["AP2 Types Package"]:::shared
        Common["Python Common Library"]:::shared
    end

    %% Python Microservices
    subgraph "Python Microservices"
        subgraph "Shopping Agent Microservice"
            Shop["Shopping Agent"]:::backend
            PMC["Payment Method Collector"]:::backend
            SAC["Shipping Address Collector"]:::backend
            Shopper["Shopper"]:::backend
        end
        CPA["Credentials Provider Agent"]:::backend
        MA["Merchant Agent"]:::backend
        MPPA["Merchant Payment Processor Agent"]:::backend
    end

    %% Android App
    subgraph "Android Shopping Assistant App"
        UI["UI & ViewModel"]:::client
        A2A["A2A Client & Builder"]:::client
        Data["Data & Repository"]:::client
    end

    %% Orchestration Scripts
    subgraph "Orchestration Scripts"
        PyOrch["Python Scenario run.sh"]:::orchestration
        AndOrch["Android Scenario run.sh"]:::orchestration
        RootOrch["Root run.sh"]:::orchestration
    end

    %% External Services
    LLM["Gemini LLM API"]:::external
    Docs["Documentation Site (MkDocs)"]:::external

    %% Connections
    UI --> A2A
    A2A -->|"HTTP JSON over A2A"| Shop

    Shop --> PMC
    Shop --> SAC
    Shop --> Shopper
    Shop --> CPA
    Shop --> MA
    Shop --> MPPA
    Shop --> Common

    CPA --> Common
    MA --> Common
    MPPA --> Common

    Shop -->|LLM API calls| LLM
    CPA -->|LLM API calls| LLM
    MA -->|LLM API calls| LLM
    MPPA -->|LLM API calls| LLM

    PyOrch --> Shop
    PyOrch --> CPA
    PyOrch --> MA
    PyOrch --> MPPA

    AndOrch --> UI
    RootOrch --> PyOrch
    RootOrch --> AndOrch

    Docs --- Types
    Docs --- Common
    Docs --- Shop

    %% Click Events
    click Types "https://github.com/google-agentic-commerce/ap2/tree/main/src/ap2/types"
    click Common "https://github.com/google-agentic-commerce/ap2/tree/main/samples/python/src/common"
    click Shop "https://github.com/google-agentic-commerce/ap2/tree/main/samples/python/src/roles/shopping_agent"
    click PMC "https://github.com/google-agentic-commerce/ap2/tree/main/samples/python/src/roles/shopping_agent/subagents/payment_method_collector"
    click SAC "https://github.com/google-agentic-commerce/ap2/tree/main/samples/python/src/roles/shopping_agent/subagents/shipping_address_collector"
    click Shopper "https://github.com/google-agentic-commerce/ap2/tree/main/samples/python/src/roles/shopping_agent/subagents/shopper"
    click CPA "https://github.com/google-agentic-commerce/ap2/tree/main/samples/python/src/roles/credentials_provider_agent"
    click MA "https://github.com/google-agentic-commerce/ap2/tree/main/samples/python/src/roles/merchant_agent"
    click MPPA "https://github.com/google-agentic-commerce/ap2/tree/main/samples/python/src/roles/merchant_payment_processor_agent"
    click UI "https://github.com/google-agentic-commerce/ap2/tree/main/samples/android/shopping_assistant/app/src/main/java/com/example/a2achatassistant/ui"
    click A2A "https://github.com/google-agentic-commerce/ap2/tree/main/samples/android/shopping_assistant/app/src/main/java/com/example/a2achatassistant/a2a"
    click Data "https://github.com/google-agentic-commerce/ap2/tree/main/samples/android/shopping_assistant/app/src/main/java/com/example/a2achatassistant/data"
    click PyOrch "https://github.com/google-agentic-commerce/ap2/blob/main/samples/python/scenarios/a2a/human-present/*/run.sh"
    click AndOrch "https://github.com/google-agentic-commerce/ap2/blob/main/samples/android/scenarios/digital-payment-credentials/run.sh"
    click RootOrch "https://github.com/google-agentic-commerce/ap2/blob/main/run.sh"
    click Docs "https://github.com/google-agentic-commerce/ap2/tree/main/docs/"

    %% Styles
    classDef backend fill:#cce5ff,stroke:#004085,color:#004085
    classDef client fill:#d4edda,stroke:#155724,color:#155724
    classDef shared fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef orchestration fill:#f8d7da,stroke:#721c24,color:#721c24
```
