# temporalio/sdk-java architecture

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

- Interactive diagram: https://gitdiagram.com/temporalio/sdk-java
- Repository: https://github.com/temporalio/sdk-java

## Overview

Temporal Java SDK is a framework for authoring and operating durable workflows and activities. The main user flow is application code configuring a client and starting a workflow; Temporal Service persists execution state and schedules work; workers run workflow and activity code, report outcomes, and the client retrieves results. The repository also includes workflow streams, payload storage, Spring AI/MCP integrations, Kotlin extensions, configuration loading, and observability plugins. The tree and excerpts support the product boundaries, but not detailed wiring for most unsampled modules, so those links are omitted.

Main entry points: [`temporal-sdk`](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk) (Worker Runtime), [`temporal-sdk/src/main/java/io/temporal/client`](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/client) (Workflow Client), [`temporal-sdk/src/main/java/io/temporal/workflow`](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/workflow) (Workflow APIs), [`temporal-sdk/src/main/java/io/temporal/common/converter`](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/common/converter) (Payload Conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Workflow Runtime"]
  node_client["Workflow Client"]
  node_workflow["Workflow APIs"]
  node_activity["Activity APIs"]
  node_worker["Worker Runtime"]
  node_payload["Payload Conversion"]
  node_storage_api["Payload Storage API"]
end

subgraph group_extensions["Developer Extensions"]
  node_streams["Workflow Streams"]
  node_kotlin["Kotlin Extensions"]
  node_encoder["Remote Data Encoder"]
end

subgraph group_integrations["External Integrations"]
  node_s3_driver["S3 Storage Driver"]
  node_spring_ai["Spring AI Integration"]
  node_chat["Chat Activities"]
  node_mcp["MCP Activities"]
end

subgraph group_operations["Configuration And Telemetry"]
  node_envconfig["Client Configuration"]
  node_otel["OpenTelemetry Plugins"]
  node_tracing["OpenTracing Interceptors"]
end

node_developer(("Application Developer"))
node_service[("Temporal Service")]
node_s3[("Amazon S3")]
node_ai_services["AI And MCP Services"]
node_telemetry["Telemetry Backend"]

node_developer -->|"authors"| node_workflow
node_developer -->|"implements"| node_activity
node_developer -->|"starts workflows"| node_client
node_client -->|"sends requests"| node_service
node_service -->|"dispatches tasks"| node_worker
node_worker -->|"runs workflows"| node_workflow
node_worker -->|"runs activities"| node_activity
node_worker -->|"reports outcomes"| node_service
node_client -->|"reads results"| node_service
node_workflow -->|"encodes data"| node_payload
node_payload -->|"stores payloads"| node_storage_api
node_storage_api -.->|"selects driver"| node_s3_driver
node_s3_driver -->|"reads and writes"| node_s3
node_developer -->|"uses stream APIs"| node_streams
node_streams -->|"runs in workflows"| node_workflow
node_developer -->|"configures integration"| node_spring_ai
node_spring_ai -->|"registers activities"| node_chat
node_spring_ai -->|"registers activities"| node_mcp
node_chat -->|"calls models"| node_ai_services
node_mcp -->|"calls tools"| node_ai_services
node_developer -->|"uses extensions"| node_kotlin
node_kotlin -->|"extends API"| node_workflow
node_developer -->|"loads settings"| node_envconfig
node_envconfig -->|"configures client"| node_client
node_payload -.->|"encodes payloads"| node_encoder
node_worker -.->|"exports metrics"| node_otel
node_client -.->|"intercepts calls"| node_tracing
node_worker -.->|"intercepts execution"| node_tracing
node_otel -.->|"exports telemetry"| node_telemetry
node_tracing -.->|"exports spans"| node_telemetry

click node_client "https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/client"
click node_workflow "https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/workflow"
click node_activity "https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/activity"
click node_worker "https://github.com/temporalio/sdk-java/tree/main/temporal-sdk"
click node_payload "https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/common/converter"
click node_storage_api "https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/payload/storage"
click node_s3_driver "https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-payload-storage-s3driver/src/main/java/io/temporal/payload/storage/s3driver"
click node_streams "https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-workflowstreams/src/main/java/io/temporal/workflowstreams"
click node_spring_ai "https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-spring-ai/src/main/java/io/temporal/springai"
click node_chat "https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-spring-ai/src/main/java/io/temporal/springai/activity"
click node_mcp "https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-spring-ai/src/main/java/io/temporal/springai/mcp"
click node_kotlin "https://github.com/temporalio/sdk-java/tree/main/temporal-kotlin/src/main/kotlin/io/temporal"
click node_envconfig "https://github.com/temporalio/sdk-java/tree/main/temporal-envconfig/src/main/java/io/temporal/envconfig"
click node_encoder "https://github.com/temporalio/sdk-java/tree/main/temporal-remote-data-encoder/src/main/java/io/temporal/payload/codec"
click node_otel "https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-opentelemetry/src/main/java/io/temporal/opentelemetry"
click node_tracing "https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-opentracing/src/main/java/io/temporal/opentracing"

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,node_workflow,node_activity,node_worker,node_payload,node_storage_api toneBlue
class node_streams,node_kotlin,node_encoder,node_service,node_s3 toneAmber
class node_s3_driver,node_spring_ai,node_chat,node_mcp toneMint
class node_envconfig,node_otel,node_tracing toneRose
class node_developer,node_ai_services,node_telemetry toneIndigo
```

## Components

### Workflow Runtime

- [Workflow Client](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/client): `temporal-sdk/src/main/java/io/temporal/client`
- [Workflow APIs](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/workflow): `temporal-sdk/src/main/java/io/temporal/workflow`
- [Activity APIs](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/activity): `temporal-sdk/src/main/java/io/temporal/activity`
- [Worker Runtime](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk): `temporal-sdk`
- [Payload Conversion](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/common/converter): `temporal-sdk/src/main/java/io/temporal/common/converter`
- [Payload Storage API](https://github.com/temporalio/sdk-java/tree/main/temporal-sdk/src/main/java/io/temporal/payload/storage): `temporal-sdk/src/main/java/io/temporal/payload/storage`

### Developer Extensions

- [Workflow Streams](https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-workflowstreams/src/main/java/io/temporal/workflowstreams): `contrib/temporal-workflowstreams/src/main/java/io/temporal/workflowstreams`
- [Kotlin Extensions](https://github.com/temporalio/sdk-java/tree/main/temporal-kotlin/src/main/kotlin/io/temporal): `temporal-kotlin/src/main/kotlin/io/temporal`
- [Remote Data Encoder](https://github.com/temporalio/sdk-java/tree/main/temporal-remote-data-encoder/src/main/java/io/temporal/payload/codec): `temporal-remote-data-encoder/src/main/java/io/temporal/payload/codec`

### External Integrations

- [S3 Storage Driver](https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-payload-storage-s3driver/src/main/java/io/temporal/payload/storage/s3driver): `contrib/temporal-payload-storage-s3driver/src/main/java/io/temporal/payload/storage/s3driver`
- [Spring AI Integration](https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-spring-ai/src/main/java/io/temporal/springai): `contrib/temporal-spring-ai/src/main/java/io/temporal/springai`
- [Chat Activities](https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-spring-ai/src/main/java/io/temporal/springai/activity): `contrib/temporal-spring-ai/src/main/java/io/temporal/springai/activity`
- [MCP Activities](https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-spring-ai/src/main/java/io/temporal/springai/mcp): `contrib/temporal-spring-ai/src/main/java/io/temporal/springai/mcp`

### Configuration And Telemetry

- [Client Configuration](https://github.com/temporalio/sdk-java/tree/main/temporal-envconfig/src/main/java/io/temporal/envconfig): `temporal-envconfig/src/main/java/io/temporal/envconfig`
- [OpenTelemetry Plugins](https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-opentelemetry/src/main/java/io/temporal/opentelemetry): `contrib/temporal-opentelemetry/src/main/java/io/temporal/opentelemetry`
- [OpenTracing Interceptors](https://github.com/temporalio/sdk-java/tree/main/contrib/temporal-opentracing/src/main/java/io/temporal/opentracing): `contrib/temporal-opentracing/src/main/java/io/temporal/opentracing`

### Other components

- **Application Developer**
- **Temporal Service**
- **Amazon S3**
- **AI And MCP Services**
- **Telemetry Backend**

## Connections

- Application Developer → Workflow APIs: authors
- Application Developer → Activity APIs: implements
- Application Developer → Workflow Client: starts workflows
- Workflow Client → Temporal Service: sends requests
- Temporal Service → Worker Runtime: dispatches tasks
- Worker Runtime → Workflow APIs: runs workflows
- Worker Runtime → Activity APIs: runs activities
- Worker Runtime → Temporal Service: reports outcomes
- Workflow Client → Temporal Service: reads results
- Workflow APIs → Payload Conversion: encodes data
- Payload Conversion → Payload Storage API: stores payloads
- Payload Storage API → S3 Storage Driver: selects driver
- S3 Storage Driver → Amazon S3: reads and writes
- Application Developer → Workflow Streams: uses stream APIs
- Workflow Streams → Workflow APIs: runs in workflows
- Application Developer → Spring AI Integration: configures integration
- Spring AI Integration → Chat Activities: registers activities
- Spring AI Integration → MCP Activities: registers activities
- Chat Activities → AI And MCP Services: calls models
- MCP Activities → AI And MCP Services: calls tools
- Application Developer → Kotlin Extensions: uses extensions
- Kotlin Extensions → Workflow APIs: extends API
- Application Developer → Client Configuration: loads settings
- Client Configuration → Workflow Client: configures client
- Payload Conversion → Remote Data Encoder: encodes payloads
- Worker Runtime → OpenTelemetry Plugins: exports metrics
- Workflow Client → OpenTracing Interceptors: intercepts calls
- Worker Runtime → OpenTracing Interceptors: intercepts execution
- OpenTelemetry Plugins → Telemetry Backend: exports telemetry
- OpenTracing Interceptors → Telemetry Backend: exports spans