# orkes-io/orkes-conductor-client architecture

> Architecture diagram of the GitHub repository orkes-io/orkes-conductor-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orkes-io/orkes-conductor-client
- Repository: https://github.com/orkes-io/orkes-conductor-client

## Overview

##### Project Type and Purpose
- This is an open-source Java SDK (client library) for the Orkes Conductor orchestration server.
- It is not a standalone application but a reusable client that:
- Exposes methods to configure and invoke Conductor workflows and tasks
- Provides pluggable HTTP and gRPC transports
- Integrates with secret managers (AWS, Azure) and external services (Kafka, AI integrations)
- Offers Spring Boot auto-configuration

##### File Structure
- Top-level buckets:
- src/ — main and test Java code
- examples/ — sample usage (helloworld, dynamic workflow, task workers)
- docs/ — markdown guides (AUTH, METADATA, worker and workflow patterns, Kafka queue)
- build.gradle, gradle/ wrapper/ — build and CI scripts
- .github/workflows — CI for tests, OSS publishing, release

- src/main/java split into two roots:
1. com.netflix.conductor.client/... — legacy Netflix Conductor client code
2. io.orkes.conductor.client/... — Orkes-branded client layers, including:
- ApiClient, OrkesClients façade
- HTTP layer under client/http (OpenAPI-generated API classes, interceptors, auth)
- gRPC layer under client/grpc (ChannelManager, pooled pollers, stream handlers)
- Automator (TaskRunner) and WorkerFn abstractions
- Model classes grouping API request/response DTOs
- SecretsManager abstractions for AWS/Azure
- Spring Boot auto-configuration

- Configuration & metadata:
- src/main/resources/service_config.json — default API endpoints
- Optional override via ApiClient constructor or Spring beans

##### README Insights
- Purpose: provide instructions to add SDK via Gradle/Maven, write “Hello World” workflows and workers.
- Demonstrates dynamic workflow creation, worker methods annotated with @WorkerTask, Main application launching WorkflowExecutor.
- Mentions Conductor server (Docker), external UI, and credentials (API key/secret).

##### Key Points to Capture
- Separation between transport layers (HTTP vs. gRPC) and common interfaces
- The polling-and-execution loop (TaskRunner) as the heart of the worker model
- How Workflow definitions map to client calls (WorkflowExecutor → Conductor REST API)
- Pluggable secret and integration clients, demonstrating extensibility
- Sample usage path: Main → ApiClient → WorkflowExecutor → worker methods → Conductor server

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code
    subgraph "User Application" 
        direction TB
        AppInit("Main Application<br/>(Main.java)"):::user
        WorkflowDef("Workflow Definitions"):::user
        WorkerClasses("Worker Classes<br/>(@WorkerTask)"):::user
    end

    %% SDK Core
    subgraph "Orkes Java SDK" 
        direction TB
        ApiClient["ApiClient<br/>(core HTTP/gRPC)"]:::core
        OrkesClients["OrkesClients Facade"]:::core
        CoreInterfaces["Core Client Interfaces<br/>(TaskClient, WorkflowClient, MetadataClient)"]:::core
        ModelClasses["Model Classes<br/>(DTOs & AI models)"]:::core
        LegacyLayer["Legacy Conductor Client<br/>(com.netflix.conductor)"]:::core

        subgraph "HTTP Transport Module"
            direction TB
            HTTPModule["HTTP Transport<br/>(OpenAPI & OkHttp)"]:::core
            HTTPModels["HTTP API Models"]:::core
            HTTPAuth["HTTP Auth Handlers"]:::core
        end

        subgraph "gRPC Transport Module"
            direction TB
            GRPCModule["gRPC Transport"]:::core
            GRPCWorkflow["gRPC Workflow Clients"]:::core
        end

        subgraph Automator
            direction TB
            TaskRunner["TaskRunner"]:::core
            TaskConfigurer["TaskRunnerConfigurer"]:::core
            WorkerFn["WorkerFn"]:::core
        end

        subgraph "Secrets Manager Plugins"
            direction TB
            AwsSM["AwsSecretsManager"]:::core
            AzureSM["AzureSecretsManager"]:::core
        end

        SpringConfig["Spring Boot Auto-Configuration"]:::core
        ServiceConfig["Service Configuration<br/>(service_config.json)"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        ConductorServer["Orkes Conductor Server<br/>(REST/gRPC)"]:::external
        SecretStore["Secret Stores<br/>(AWS, Azure)"]:::external
        Kafka["Kafka Broker"]:::external
        AI["LLM / AI Integrations"]:::external
    end

    %% Relationships
    AppInit -->|initializes| ApiClient
    AppInit -->|defines workflows| WorkflowDef
    AppInit -->|registers| WorkerClasses

    ApiClient -->|uses| OrkesClients
    OrkesClients -->|implements| CoreInterfaces
    OrkesClients -->|uses| HTTPModule
    OrkesClients -->|uses| GRPCModule
    HTTPModule --> HTTPModels
    HTTPModule --> HTTPAuth
    GRPCModule --> GRPCWorkflow

    ApiClient -->|loads config| ServiceConfig
    ApiClient -->|injects via Spring| SpringConfig

    TaskRunner -->|polls tasks via| CoreInterfaces
    TaskRunner -->|dispatches to| WorkerFn
    TaskConfigurer --> TaskRunner

    WorkerClasses -->|implements| WorkerFn
    WorkflowDef -->|submitted via| CoreInterfaces
    CoreInterfaces -->|calls| ConductorServer
    TaskRunner -->|polls| ConductorServer

    AwsSM -->|fetches secrets from| SecretStore
    AzureSM -->|fetches secrets from| SecretStore
    ApiClient -->|uses| AwsSM
    ApiClient -->|uses| AzureSM

    AI -->|called by| HTTPModule
    Kafka -->|used by| HTTPModule

    SpringConfig -->|configures beans| ApiClient
    SpringConfig -->|configures beans| TaskRunner

    %% Click Events
    click ApiClient "https://github.com/orkes-io/orkes-conductor-client/blob/main/src/main/java/io/orkes/conductor/client/ApiClient.java"
    click OrkesClients "https://github.com/orkes-io/orkes-conductor-client/blob/main/src/main/java/io/orkes/conductor/client/OrkesClients.java"
    click HTTPModule "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/io/orkes/conductor/client/http"
    click HTTPModels "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/io/orkes/conductor/client/http/api"
    click HTTPAuth "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/io/orkes/conductor/client/http/auth"
    click GRPCModule "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/io/orkes/conductor/client/grpc"
    click GRPCWorkflow "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/io/orkes/conductor/client/grpc/workflow"
    click TaskRunner "https://github.com/orkes-io/orkes-conductor-client/blob/main/src/main/java/io/orkes/conductor/client/automator/TaskRunner.java"
    click TaskConfigurer "https://github.com/orkes-io/orkes-conductor-client/blob/main/src/main/java/io/orkes/conductor/client/automator/TaskRunnerConfigurer.java"
    click WorkerFn "https://github.com/orkes-io/orkes-conductor-client/blob/main/src/main/java/io/orkes/conductor/client/WorkerFn.java"
    click AwsSM "https://github.com/orkes-io/orkes-conductor-client/blob/main/src/main/java/io/orkes/conductor/client/secrets/manager/aws/AwsSecretsManager.java"
    click AzureSM "https://github.com/orkes-io/orkes-conductor-client/blob/main/src/main/java/io/orkes/conductor/client/secrets/manager/azure/AzureSecretsManager.java"
    click SpringConfig "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/io/orkes/conductor/client/spring"
    click CoreInterfaces "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/io/orkes/conductor/client"
    click ModelClasses "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/io/orkes/conductor/client/model"
    click LegacyLayer "https://github.com/orkes-io/orkes-conductor-client/tree/main/src/main/java/com/netflix/conductor/client"
    click ServiceConfig "https://github.com/orkes-io/orkes-conductor-client/blob/main/src/main/resources/service_config.json"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef user fill:#DFFFE0,stroke:#0a8f08,color:#0a8f08
    classDef external fill:#FFE8C0,stroke:#d76a00,color:#d76a00
```
