# googleapis/java-genai architecture

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

- Interactive diagram: https://gitdiagram.com/googleapis/java-genai
- Repository: https://github.com/googleapis/java-genai

## Overview

##### Project type and purpose
- This is a Java-idiomatic client SDK library for Google’s Gen AI services (Gemini Developer APIs and Vertex AI).
- It provides a uniform, fluent, and type-safe interface for Java applications to invoke remote AI endpoints (synchronous, asynchronous, streaming, function calling, etc.).

##### High-level architectural components
1. **Consumer Layer**
- Your application code or the `examples/` module that calls the SDK’s public API (`com.google.genai.Client`, `client.models`, `client.async`, `ResponseStream`, etc.).
2. **Public SDK API Layer**
- The facade classes under `src/main/java/com/google/genai`:
- Client & Client.Builder
- Sync entry points (`Client.models`, `Client.chat`, `Client.files`, `Client.operations`, etc.)
- Async entry points under `Client.async.*`
- Streaming API (`ResponseStream`)
- Domain abstractions (`GenerateContentConfig`, `Tool`, `Content`, `Schema`, etc.).
3. **Core Infrastructure Layer**
- **Transport abstraction**:
- `ApiClient` interface (strategy for HTTP calls)
- `HttpApiClient` (real HTTP/JSON over REST)
- `ReplayApiClient` (record/replay for testing)
- **Serialization/Deserialization**:
- `Transformers`, `JsonSerializable`, `ResponseStream` converters
- **Helper patterns**:
- Paging: `BasePager` / `AsyncPager`
- Caching: `Caches` / `AsyncCaches`
- Error handling: exceptions under `errors/` and `ApiResponse` wrappers
- **Configuration & Utilities**:
- `DebugConfig`, `Common`, `AfcUtil`
4. **External Service Layer**
- REST endpoints of Gemini Developer API
- REST endpoints of Vertex AI API
- Authentication & environment (API Key, OAuth, Service Account, Google Cloud Project/Location)

##### Relationships and data flow
- **Application → Public SDK API**:
The application invokes methods on `Client` (e.g., `client.models.generateContent(...)`).
- **Public SDK API → Core Infrastructure**:
The facade translates method calls into typed request objects and passes them to `ApiClient`.
- **Core Infrastructure → External Service**:
`HttpApiClient` serializes requests to JSON, sends HTTP requests, parses JSON responses into domain types.
- **Error/Retry/Caching**:
On errors, exceptions from `ApiClient` propagate up; caching layers may intercept certain calls.
- **Async & Streaming**:
Async calls wrap `CompletableFuture`; streaming calls yield a `ResponseStream<T>` that lazily fetches HTTP chunks.

##### Architectural patterns and design principles
- **Facade Pattern**: `Client` as single entry point
- **Builder Pattern**: `Client.builder()`, `GenerateContentConfig.builder()`, `Tool.builder()`
- **Strategy Pattern**: Pluggable `ApiClient` implementations (`HttpApiClient`, `ReplayApiClient`)
- **Adapter Pattern**: Translating between domain types and JSON payloads via `Transformers`
- **Separation of Concerns**: Public API → Transport → External service
- **Testability**: `ReplayApiClient` + abundant unit tests under `src/test/java`

##### Essential details to capture
- All public entry points (`Client`, `client.async`, streaming vs. unary calls).
- The transport abstraction (`ApiClient`) and its two implementations.
- The JSON ↔ domain‐object conversion layer (`Transformers`, `JsonSerializable`).
- Error path via `ApiException`, `ServerException`, `ClientException`.
- Configuration via environment variables vs. builder overrides.
- Paging & streaming mechanics (`BasePager`, `AsyncPager`, `ResponseStream`).

## Diagram (Mermaid)

```mermaid
graph TD
  %% Consumer Layer
  subgraph "Consumer Layer"
    Examples["Examples / Application"]:::consumer
  end

  %% Public SDK API Layer
  subgraph "Public SDK API" 
    Client["Client (Facade)"]:::publicapi
    Models["Models"]:::publicapi
    Chats["Chats"]:::publicapi
    Files["Files"]:::publicapi
    Operations["Operations"]:::publicapi
    AsyncModels["AsyncModels"]:::publicapi
    AsyncChats["AsyncChats"]:::publicapi
    AsyncFiles["AsyncFiles"]:::publicapi
    AsyncOperations["AsyncOperations"]:::publicapi
    ResponseStream["ResponseStream"]:::publicapi
    GenCfg["GenerateContentConfig"]:::publicapi
    Tool["Tool"]:::publicapi
    Content["Content"]:::publicapi
    Schema["Schema"]:::publicapi
  end

  %% Core Infrastructure Layer
  subgraph "Core Infrastructure" 
    ApiClient["ApiClient"]:::core
    HttpApiClient["HttpApiClient"]:::core
    ReplayApiClient["ReplayApiClient"]:::core
    Transformers["Transformers"]:::core
    JsonSerializable["JsonSerializable"]:::core
    LiveConv["LiveConverters"]:::core
    TokenConv["TokensConverters"]:::core
    BasePager["BasePager"]:::core
    AsyncPager["AsyncPager"]:::core
    Caches["Caches"]:::core
    AsyncCaches["AsyncCaches"]:::core
    ApiException["ApiException"]:::core
    ClientException["ClientException"]:::core
    ServerException["ServerException"]:::core
    ApiResponse["ApiResponse"]:::core
    DebugConfig["DebugConfig"]:::core
    Common["Common"]:::core
    AfcUtil["AfcUtil"]:::core
  end

  %% External Service Layer
  subgraph "External Service Layer"
    GeminiAPI["Gemini Developer API"]:::external
    VertexAPI["Vertex AI API"]:::external
    AuthEnv["Auth & Env"]:::external
  end

  %% Connections
  Examples -->|"invokes"| Client
  Client -->|"calls"| Models
  Client -->|"calls"| Chats
  Client -->|"calls"| Files
  Client -->|"calls"| Operations
  Client -->|"builder uses"| DebugConfig
  Client -->|"builder uses"| Common
  Client -->|"builder uses"| AfcUtil

  Models -->|"build request"| GenCfg
  Models -->|"uses domain"| Tool
  Models -->|"uses domain"| Content
  Models -->|"uses domain"| Schema

  Models -->|"sync call"| ApiClient
  Chats -->|"sync call"| ApiClient
  Files -->|"sync call"| ApiClient
  Operations -->|"sync call"| ApiClient

  AsyncModels -->|"async call"| ApiClient
  AsyncChats -->|"async call"| ApiClient
  AsyncFiles -->|"async call"| ApiClient
  AsyncOperations -->|"async call"| ApiClient

  ResponseStream -->|"stream call"| ApiClient

  Models -->|"paging"| BasePager
  AsyncModels -->|"paging"| AsyncPager

  Models -->|"caching"| Caches
  AsyncModels -->|"caching"| AsyncCaches

  ApiClient -->|"strategy"| HttpApiClient
  ApiClient -->|"strategy"| ReplayApiClient

  HttpApiClient -->|"serialize JSON"| Transformers
  HttpApiClient -->|"serialize JSON"| JsonSerializable
  HttpApiClient -->|"serialize JSON"| LiveConv
  HttpApiClient -->|"serialize JSON"| TokenConv

  HttpApiClient -->|"HTTP POST"| GeminiAPI
  HttpApiClient -->|"HTTP POST"| VertexAPI
  HttpApiClient -->|"use auth"| AuthEnv

  HttpApiClient -->|"wrap response"| ApiResponse
  ApiResponse -->|"on error"| ApiException
  ApiException -->|"is instance of"| ClientException
  ApiException -->|"is instance of"| ServerException

  %% Click Events Consumer
  click Examples "https://github.com/googleapis/java-genai/tree/main/examples/src/main/java/com/google/genai/examples"

  %% Click Events Public SDK API
  click Client "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/Client.java"
  click Models "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/Models.java"
  click Chats "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/Chats.java"
  click Files "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/Files.java"
  click Operations "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/Operations.java"
  click AsyncModels "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/AsyncModels.java"
  click AsyncChats "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/AsyncChats.java"
  click AsyncFiles "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/AsyncFiles.java"
  click AsyncOperations "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/AsyncOperations.java"
  click ResponseStream "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/ResponseStream.java"
  click GenCfg "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/types/GenerateContentConfig.java"
  click Tool "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/types/Tool.java"
  click Content "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/types/Content.java"
  click Schema "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/types/Schema.java"

  %% Click Events Core Infrastructure
  click ApiClient "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/ApiClient.java"
  click HttpApiClient "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/HttpApiClient.java"
  click ReplayApiClient "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/ReplayApiClient.java"
  click Transformers "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/Transformers.java"
  click JsonSerializable "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/JsonSerializable.java"
  click LiveConv "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/LiveConverters.java"
  click TokenConv "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/TokensConverters.java"
  click BasePager "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/BasePager.java"
  click AsyncPager "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/AsyncPager.java"
  click Caches "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/Caches.java"
  click AsyncCaches "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/AsyncCaches.java"
  click ApiException "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/errors/ApiException.java"
  click ClientException "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/errors/ClientException.java"
  click ServerException "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/errors/ServerException.java"
  click ApiResponse "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/ApiResponse.java"
  click DebugConfig "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/DebugConfig.java"
  click Common "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/Common.java"
  click AfcUtil "https://github.com/googleapis/java-genai/blob/main/src/main/java/com/google/genai/AfcUtil.java"

  %% Click Events Tests
  click FakeUploadApiClient "https://github.com/googleapis/java-genai/blob/main/src/test/java/com/google/genai/FakeUploadApiClient.java"
  click ReplaySanitizer "https://github.com/googleapis/java-genai/blob/main/src/test/java/com/google/genai/ReplaySanitizer.java"
  click HttpApiClientTest "https://github.com/googleapis/java-genai/blob/main/src/test/java/com/google/genai/HttpApiClientTest.java"

  %% Styles
  classDef publicapi fill:#D0E6FF,stroke:#0066CC,color:#003366
  classDef core fill:#E6FFE6,stroke:#33CC33,color:#006600
  classDef external fill:#FFE6CC,stroke:#FF9933,color:#CC6600
  classDef consumer fill:#F2F2F2,stroke:#999999,color:#666666
```
