> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inferable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Learn how Inferable works through its core components: Tools, Agents, and Workflows, all connected via the Control Plane

# Introducing the Inferable Architecture

Inferable provides a robust, distributed architecture designed for building reliable AI-powered applications. Unlike traditional frameworks that require co-location of model calls and function execution, Inferable takes a fundamentally different approach, separating these concerns while maintaining persistent state throughout the entire application lifecycle.

## Architectural Overview

At a high level, Inferable's architecture consists of three primary components:

1. **Control Plane**: The central nervous system of Inferable, orchestrating all component interactions
2. **Workflows**: Stateful orchestration units that coordinate complex, multi-step processes
3. **Client SDKs**: Language-specific libraries that connect your functions to the Inferable ecosystem

These 3 components underpin all LLM-native abstractions like structured outputs, human-in-the-loop, agents, tool use and etc.

## The Control Plane: State Persistence at its Core

The Control Plane is the foundation of Inferable's architecture, providing critical services including:

### Persistent State Management

Unlike many AI orchestration frameworks, Inferable's Control Plane includes a built-in persistence layer that automatically maintains the complete state of all running workflows:

```mermaid
sequenceDiagram
    participant WF as Workflow
    participant CP as Control Plane
    participant PS as Persistence Store

    Note over WF,PS: All state changes are atomic and durable

    WF->>CP: Begin state transaction
    CP->>PS: Read current state
    PS-->>CP: Return state
    CP->>WF: Process with current state
    WF->>CP: State modification
    CP->>PS: Persist state (atomic)
    PS-->>CP: Confirm persistence
    CP-->>WF: Transaction complete
```

Key benefits of this design:

* **Automatic Checkpointing**: Every state change is persisted without developer intervention
* **Transactional Integrity**: State updates use ACID transactions to prevent corruption
* **Zero-Loss Recovery**: Workflows resume from exactly where they left off, even after system failures
* **Temporal Durability**: State can be maintained for any duration - minutes, hours, or months

### Distributed Job Queue

The Control Plane incorporates a sophisticated distributed job queue that routes function calls to the appropriate execution environments:

```mermaid
graph TD
    CP[Control Plane] --> JQ[Job Queue]
    JQ --> W1[Worker Machine 1]
    JQ --> W2[Worker Machine 2]
    JQ --> W3[Worker Machine 3]

    W1 --> F1[Workflow 1]
    W1 --> F2[Workflow 2]

    W2 --> F4[Workflow 1]
    W2 --> F5[Workflow 3]

    W3 --> F7[Workflow 2]
    W3 --> F8[Workflow 3]
    classDef primary fill:#6366f1,color:white,stroke:#4f46e5,stroke-width:2px
    classDef secondary fill:#a5b4fc,stroke:#6366f1,stroke-width:1px
    classDef tertiary fill:#ddd6fe,stroke:#a5b4fc,stroke-width:1px

    class CP,JQ primary
    class W1,W2,W3 secondary
    class F1,F2,F3 tertiary
```

This job queue provides:

* **Fair Distribution**: Balances workloads across available worker pools
* **Prioritization**: Handles urgent tasks ahead of lower-priority ones
* **Backpressure Management**: Gracefully handles capacity constraints
* **Routing Intelligence**: Directs jobs to workers with appropriate capabilities

## Long Polling: No Network Configuration Required

One of Inferable's most distinctive architectural features is its use of long polling for communication between the Control Plane and function execution environments:

```mermaid
sequenceDiagram
    participant SDK as Client SDK
    participant CP as Control Plane

    loop Long Polling
        SDK->>CP: Check for available work
        alt No work available
            CP-->>SDK: No Content (wait)
            Note over SDK,CP: Connection remains open
        else Work available
            CP-->>SDK: 200 OK (with job details)
            SDK->>SDK: Execute function
            SDK->>CP: Submit result
        end
    end
```

This approach offers significant advantages:

* **Zero Inbound Ports**: Your execution environments need no open inbound ports
* **Firewall-Friendly**: Works with standard outbound HTTPS (port 443)
* **NAT Traversal**: Functions behind NAT can still participate
* **No VPN Required**: Connect from any network with internet access
* **No DNS Configuration**: No need to set up DNS records or certificates

For organizations with strict security requirements, this means:

* Functions can run in private subnets with no internet-accessible endpoints
* No need to expose internal services to the public internet
* No complex network configuration or tunneling required
* Works seamlessly with existing security boundaries

## Workflows: Orchestrating Complex Processes

Workflows are the coordination layer in Inferable, responsible for:

* Maintaining execution context across multiple steps
* Managing transitions between different processing stages
* Handling retries, timeouts, and error conditions
* Coordinating parallel execution paths when appropriate

Each workflow maintains its own state machine, automatically persisted by the Control Plane:

```mermaid
stateDiagram-v2
    [*] --> Initializing
    Initializing --> Running
    Running --> Paused: Human approval needed
    Paused --> Running: Approval received
    Running --> Complete: Finished successfully
    Running --> Failed: Unrecoverable error
    Complete --> [*]
    Failed --> [*]

    note right of Paused
        State persisted indefinitely
        Resume with full context
    end note
```

This persistence enables powerful capabilities:

* **Indefinite Pausing**: Workflows can pause for any duration while awaiting input
* **Context Preservation**: Complete state is maintained during pauses
* **Seamless Resumption**: Execution continues with all context intact
* **Multi-Step Processes**: Complex multi-stage workflows maintain coherence