# glaforge/gemini-interactions-api-sdk architecture

> Architecture diagram of the GitHub repository glaforge/gemini-interactions-api-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/glaforge/gemini-interactions-api-sdk
- Repository: https://github.com/glaforge/gemini-interactions-api-sdk

## Overview

This repository is a Java SDK for the Gemini Interactions API, with an optional server-side HTTP webhook handler. The principal workflow is application code building typed interaction parameters, calling the client to send requests to Gemini, then consuming a structured or streamed interaction response. The client also exposes resource-management operations for agents, environments and files, voices, triggers, and webhooks. Models and custom Jackson handling represent the API’s polymorphic interaction data; schema utilities support tool schemas. Source excerpts are partial, so unsampled resource-operation wiring is represented at the client boundary only.

Main entry points: [`gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/GeminiInteractionsClient.java`](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/GeminiInteractionsClient.java) (Interactions client), [`gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Interaction.java`](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Interaction.java) (Interaction models), [`gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/EnvironmentWorkspace.java`](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/EnvironmentWorkspace.java) (Environment files), [`gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/deserializer/InteractionInputDeserializer.java`](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/deserializer/InteractionInputDeserializer.java) (Input decoding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interactions"]
  node_client["Interactions client"]
end

subgraph group_resources["API resources"]
  node_agent_env["Agents and environments<br/>[Agent.java]"]
  node_environment_files["Environment files"]
  node_tar_parser["TAR index<br/>[TarParser.java]"]
  node_voice["Voice resources<br/>[Voice.java]"]
  node_trigger["Triggers<br/>[Trigger.java]"]
  node_webhook["Webhooks<br/>[Webhook.java]"]
end

subgraph group_representation["Models and schemas"]
  node_interaction_models["Interaction models<br/>[Interaction.java]"]
  node_input_codec["Input decoding"]
  node_step_models["Step and content types<br/>[Step.java]"]
  node_schema["Tool schemas<br/>[GSchema.java]"]
end

subgraph group_server["Server handler"]
  node_handler["HTTP handler"]
end

node_app(("Java application"))
node_api{{"Gemini API"}}
node_webhook_caller(("Webhook host"))

node_app -->|"calls"| node_client
node_client -->|"sends requests"| node_api
node_api -->|"returns responses"| node_client
node_client -->|"decodes responses"| node_interaction_models
node_client -->|"decodes inputs"| node_input_codec
node_input_codec -->|"constructs turns"| node_interaction_models
node_interaction_models -->|"contains steps"| node_step_models
node_app -->|"defines schemas"| node_schema
node_app -->|"manages resources"| node_agent_env
node_app -->|"handles files"| node_environment_files
node_environment_files -->|"indexes TAR"| node_tar_parser
node_app -->|"manages voices"| node_voice
node_app -->|"manages triggers"| node_trigger
node_app -->|"manages webhooks"| node_webhook
node_webhook_caller -->|"sends HTTP requests"| node_handler
node_handler -.->|"delegates API operations"| node_client

click node_client "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/GeminiInteractionsClient.java"
click node_interaction_models "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Interaction.java"
click node_input_codec "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/deserializer/InteractionInputDeserializer.java"
click node_step_models "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Step.java"
click node_schema "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/schema/GSchema.java"
click node_agent_env "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Agent.java"
click node_environment_files "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/EnvironmentWorkspace.java"
click node_tar_parser "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/TarParser.java"
click node_voice "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Voice.java"
click node_trigger "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Trigger.java"
click node_webhook "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Webhook.java"
click node_handler "https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-server/src/main/java/io/github/glaforge/gemini/interactions/server/InteractionsHandler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client toneBlue
class node_agent_env,node_environment_files,node_tar_parser,node_voice,node_trigger,node_webhook toneAmber
class node_interaction_models,node_input_codec,node_step_models,node_schema,node_api,node_webhook_caller toneMint
class node_handler toneRose
class node_app toneIndigo
```

## Components

### Interactions

- [Interactions client](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/GeminiInteractionsClient.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/GeminiInteractionsClient.java`

### API resources

- [Agents and environments](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Agent.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Agent.java`
- [Environment files](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/EnvironmentWorkspace.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/EnvironmentWorkspace.java`
- [TAR index](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/TarParser.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/TarParser.java`
- [Voice resources](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Voice.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Voice.java`
- [Triggers](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Trigger.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Trigger.java`
- [Webhooks](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Webhook.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Webhook.java`

### Models and schemas

- [Interaction models](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Interaction.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Interaction.java`
- [Input decoding](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/deserializer/InteractionInputDeserializer.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/deserializer/InteractionInputDeserializer.java`
- [Step and content types](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Step.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/interactions/model/Step.java`
- [Tool schemas](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/schema/GSchema.java): `gemini-interactions-api-sdk/src/main/java/io/github/glaforge/gemini/schema/GSchema.java`

### Server handler

- [HTTP handler](https://github.com/glaforge/gemini-interactions-api-sdk/blob/main/gemini-interactions-server/src/main/java/io/github/glaforge/gemini/interactions/server/InteractionsHandler.java): `gemini-interactions-server/src/main/java/io/github/glaforge/gemini/interactions/server/InteractionsHandler.java`

### Other components

- **Java application**
- **Gemini API**
- **Webhook host**

## Connections

- Java application → Interactions client: calls
- Interactions client → Gemini API: sends requests
- Gemini API → Interactions client: returns responses
- Interactions client → Interaction models: decodes responses
- Interactions client → Input decoding: decodes inputs
- Input decoding → Interaction models: constructs turns
- Interaction models → Step and content types: contains steps
- Java application → Tool schemas: defines schemas
- Java application → Agents and environments: manages resources
- Java application → Environment files: handles files
- Environment files → TAR index: indexes TAR
- Java application → Voice resources: manages voices
- Java application → Triggers: manages triggers
- Java application → Webhooks: manages webhooks
- Webhook host → HTTP handler: sends HTTP requests
- HTTP handler → Interactions client: delegates API operations