# infobip/omnia-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/infobip/omnia-sdk
- Repository: https://github.com/infobip/omnia-sdk

## Overview

##### Project type and purpose
- This is an open-source Python SDK (omnia_sdk) for building and deploying AI-driven, stateful workflows (e.g., chatbots) on Infobip’s distributed CPaaS/AI platform.
- It provides a LangGraph-based orchestration layer, helper “tools” modules (AI, channels, localization, contact center, etc.), and examples for local development, code submission, and HTTP APIs.

##### File structure
- Top level:
– omnia_sdk/ – the SDK package
- examples/ – sample scripts (http_api_example.py, tiny_chatbot.py)
- workflow/ – core orchestration modules:
- chatbot (configuration, state, constants)
- langgraph (graph definitions, commands, checkpointing)
- script_examples – ready-to-run sample workflows (get_logs, code_submission, etc.)
- tools/ – pluggable adapters: ai (LLM, RAG, prompts), channels (WhatsApp, OmniChannels), cdp, contact_center, localization, rest (retry client)
- tests/ – unit tests covering workflows, tools, retryable HTTP client, translation
– pyproject.toml – build and dependency management
– code_submission.py (under script_examples) – client for packaging & uploading to the platform

##### Extract insights from the README
- SDK targets Infobip’s platform to ensure distributed session management, HA, scalability, automatic language detection/localization.
- Workflows run locally or on the platform via two HTTP entry points (/inbound-api, /inbound-api-callback) and via OmniChannel API.
- Deployment: zip project tree + required YAMLs (chatbot_configuration.yaml, translation_table.yaml, optional build.yaml).

##### Main components
A. Developer Environment
– Local code (examples + user workflows)
– omnia_sdk library
– Code submission client (script or REST call)
B. Infobip Platform
– REST endpoints for deployment (code submission)
– Workflow runtime cluster (distributed, stateful inference servers)
– HTTP endpoints for inbound traffic (/inbound-api, /inbound-api-callback)
– OmniChannel API gateway for external channels (WhatsApp, SMS, etc.)
– State store (session database/checkpointing)
– Logging & monitoring services
C. Workflow Runtime (inside platform)
– LangGraph orchestrator
- Chatbot graph nodes
- Checkpointer (state persistence)
– Tools modules
- AI adapter (LLM, RAG, prompts)
- Channels adapter (send/receive)
- Localization adapter
- Contact center adapter
- CDP adapter
- Retryable HTTP client
D. External Services
– LLM providers (OpenAI, etc.)
– CPaaS/SaaS endpoints (Infobip)
– Third-party APIs used in tools

##### Relationships and interactions
1. Developer → (uses omnia_sdk) → Local workflow code
2. Developer → (code_submission.zip) → Platform deployment endpoint
3. Platform → (unpacks & loads) → Workflow runtime
4. End user → (message) → OmniChannel API → /inbound-api → LangGraph orchestrator
5. Orchestrator → (executes graph nodes) → Tools modules → External services (LLM, translation, channels, CDP)
6. Orchestrator → (state changes) → State store
7. Orchestrator → (logging) → Logging service
8. Platform → (callbacks) → /inbound-api-callback (for async flows)

##### Architectural patterns and design principles
- Modular, pluggable “tools” architecture for each external integration
- Graph-based workflow orchestration (LangGraph) with explicit state checkpointing
- Separation of concerns: orchestration vs. integration adapters vs. configuration
- Distributed, stateful service mesh (for HA and scalability)

##### Relevant technologies & frameworks
- Python 3.12+
- LangGraph (workflow DSL)
- HTTP/REST (retryable client)
- YAML configuration (chatbot_configuration.yaml, translation_table.yaml, build.yaml)
- Infobip OmniChannel & CPaaS APIs

##### Detail without overthinking
– Break the system into as many logical components as you see in the file tree: workflow/core, tools/ai, tools/channels, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        SDKCore["SDK Core Library\n(omnia_sdk/)"]:::blue
        HttpExample["HTTP API Example\n(http_api_example.py)"]:::blue
        TinyChatbot["Tiny Chatbot Example\n(tiny_chatbot.py)"]:::blue
        CodeSubmissionClient["Code Submission Client\n(code_submission.py)"]:::blue
    end

    %% Infobip Platform
    subgraph "Infobip Platform"
        direction TB
        DeploymentEndpoint["Deployment Endpoint\n(code submission)"]:::green
        subgraph "Workflow Runtime Cluster"
            direction TB
            LangGraphOrchestrator["LangGraph Orchestrator"]:::green
            subgraph "LangGraph Core"
                direction TB
                ChatbotGraph["Chatbot Graph Definition"]:::green
                LangGraphCommands["LangGraph Commands"]:::green
                NodeCheckpointer["State Checkpointer"]:::green
            end
            subgraph "Tools Modules"
                direction TB
                AIAdapter["AI Adapter"]:::green
                RAG["RAG Assistant"]:::green
                Prompts["Prompt Definitions"]:::green
                ChatUtils["Chat Utilities"]:::green
                LLMModels["LLM Models"]:::green
                ChannelsContext["Channels Context"]:::green
                OmniChannels["OmniChannels API"]:::green
                WhatsAppClient["WhatsApp Client"]:::green
                LocalizationLoader["Translation Table Loader"]:::green
                CPAASLocalization["CPaaS Translation Table"]:::green
                ContactCenter["Contact Center Adapter"]:::green
                CDPAdapter["CDP Adapter"]:::green
                RetryClient["Retryable HTTP Client"]:::green
            end
        end
        OmniChannelAPI["OmniChannel API Gateway"]:::green
        InboundAPI["/inbound-api\nHTTP Endpoint"]:::green
        InboundCallback["/inbound-api-callback"]:::green
        StateStore["State Store"]:::green
        LoggingService["Logging & Monitoring"]:::green
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProvider["LLM Providers"]:::orange
        CPaaSAPI["Infobip CPaaS API"]:::orange
        ThirdPartyAPI["Third-party APIs"]:::orange
    end

    %% External User
    EndUser["End User"]:::orange

    %% Connections
    EndUser -->|sends message| OmniChannelAPI
    OmniChannelAPI -->|forwards| InboundAPI
    InboundAPI -->|invokes| LangGraphOrchestrator
    InboundCallback -->|callbacks| LangGraphOrchestrator

    SDKCore -->|imported by| HttpExample
    SDKCore -->|imported by| TinyChatbot
    SDKCore -->|used by| CodeSubmissionClient
    CodeSubmissionClient -->|zip & upload| DeploymentEndpoint
    DeploymentEndpoint -->|deploys to| LangGraphOrchestrator

    LangGraphOrchestrator -->|executes graph| ChatbotGraph
    LangGraphOrchestrator -->|calls| LangGraphCommands
    LangGraphOrchestrator -->|checks state| NodeCheckpointer
    LangGraphOrchestrator -->|uses| AIAdapter
    AIAdapter -->|calls| LLMProvider
    LangGraphOrchestrator -->|uses| RAG
    LangGraphOrchestrator -->|uses| Prompts
    LangGraphOrchestrator -->|uses| ChatUtils
    LangGraphOrchestrator -->|uses| LLMModels
    LangGraphOrchestrator -->|uses| ChannelsContext
    ChannelsContext -->|sends/receives| CPaaSAPI
    LangGraphOrchestrator -->|uses| OmniChannels
    OmniChannels -->|sends messages| CPaaSAPI
    LangGraphOrchestrator -->|uses| WhatsAppClient
    WhatsAppClient -->|sends messages| CPaaSAPI
    LangGraphOrchestrator -->|uses| LocalizationLoader
    LocalizationLoader -->|loads| ThirdPartyAPI
    LangGraphOrchestrator -->|uses| CPAASLocalization
    CPAASLocalization -->|loads| ThirdPartyAPI
    LangGraphOrchestrator -->|uses| ContactCenter
    ContactCenter -->|interfaces| ThirdPartyAPI
    LangGraphOrchestrator -->|uses| CDPAdapter
    CDPAdapter -->|interfaces| CPaaSAPI
    LangGraphOrchestrator -->|makes HTTP calls| RetryClient
    RetryClient -->|calls| ThirdPartyAPI
    LangGraphOrchestrator -->|persists state| StateStore
    LangGraphOrchestrator -->|logs events| LoggingService

    %% Click events
    click SDKCore "https://github.com/infobip/omnia-sdk/tree/main/omnia_sdk/"
    click HttpExample "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/examples/http_api_example.py"
    click TinyChatbot "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/examples/tiny_chatbot.py"
    click CodeSubmissionClient "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/script_examples/code_sumbission.py"
    click LangGraphOrchestrator "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/langgraph/__init__.py"
    click ChatbotGraph "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/langgraph/chatbot/chatbot_graph.py"
    click LangGraphCommands "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/langgraph/chatbot/langgraph_commands.py"
    click NodeCheckpointer "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/langgraph/chatbot/node_checkpointer.py"
    click SDKCore "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/chatbot/chatbot_configuration.py"
    click SDKCore "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/chatbot/chatbot_state.py"
    click SDKCore "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/chatbot/constants.py"
    click AIAdapter "https://github.com/infobip/omnia-sdk/tree/main/omnia_sdk/workflow/tools/ai/"
    click RAG "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/ai/rag/assistant.py"
    click Prompts "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/ai/prompts/chat.py"
    click ChatUtils "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/ai/chat_utils.py"
    click LLMModels "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/ai/llm_models.py"
    click ChannelsContext "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/channels/_context.py"
    click OmniChannels "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/channels/omni_channels.py"
    click WhatsAppClient "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/channels/whatsapp_client.py"
    click LocalizationLoader "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/localization/translation_table.py"
    click CPAASLocalization "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/localization/cpaas_translation_table.py"
    click ContactCenter "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/contact_center/agent_tools.py"
    click CDPAdapter "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/cdp/people.py"
    click RetryClient "https://github.com/infobip/omnia-sdk/blob/main/omnia_sdk/workflow/tools/rest/retryable_http_client.py"

    %% Styles
    classDef blue fill:#cce5ff,stroke:#1f77b4,color:#1f77b4
    classDef green fill:#d4edda,stroke:#2ca02c,color:#2ca02c
    classDef orange fill:#ffe5b4,stroke:#ff7f0e,color:#ff7f0e
```
