# How the TinyFlows Engine Integrates with the Workflow Domain in OpenHuman

> Discover how the TinyFlows engine integrates with the OpenHuman workflow domain using a layered architecture and capability traits for LLM prompting HTTP requests and agent tools.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: internals
- Published: 2026-08-30

---

**The TinyFlows engine integrates with OpenHuman's workflow domain through a layered architecture that separates RPC schema validation, core orchestration logic, and execution runtime, connected via capability traits (caps) that supply LLM prompting, HTTP requests, and agent tools.**

The OpenHuman repository implements a robust workflow automation system where the TinyFlows execution engine serves as the runtime core. This integration allows the workflow domain to handle high-level concerns like persistence and RPC interfaces while delegating graph interpretation to a specialized Rust engine. Understanding this architecture reveals how the system maintains clean separation between domain orchestration and execution semantics.

## Domain Structure and Entry Points

The workflow domain resides under `src/openhuman/flows/` and serves as the primary interface for flow management. This directory encapsulates the public API, core operations, and the TinyFlows engine integration.

The domain exposes JSON-RPC endpoints defined in [`src/openhuman/flows/schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/schemas.rs), which validate incoming requests before forwarding them to operation handlers. These controllers handle methods like `openhuman.flows_run` and `openhuman.flows_create`, providing the external interface for workflow interaction.

Core business logic lives in [`src/openhuman/flows/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/ops.rs), which implements functions such as `handle_create_flow` and `handle_run_flow`. These operations construct an `EngineContext` that bridges the domain layer with the execution engine, ensuring that the TinyFlows runtime receives properly validated inputs and necessary host dependencies.

## The TinyFlows Execution Engine

The actual execution logic resides in [`src/openhuman/flows/tinyflows/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/mod.rs), which exports the `TinyFlowsEngine` type and the `run_flow` entry point. Unlike the domain layer, which manages drafts and runs through database operations, the engine focuses purely on interpreting stored automation graphs.

When [`ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/ops.rs) invokes the engine, it passes an `EngineContext` containing references to the `TinyFlowsEngine` instance. The engine then reads the flow graph from the draft store and executes it turn-by-turn, resolving each node according to the graph's definition. This design keeps execution semantics isolated from persistence concerns, allowing the engine to operate as a pure Rust library without runtime overhead.

## Capability Bridge (Caps)

Integration between the engine and host services occurs through the *caps* layer located in `src/openhuman/flows/tinyflows/caps/`. Each capability implements a trait that the engine calls during execution, enabling the workflow domain to inject host-specific behavior without modifying engine code.

The four primary capabilities include:

- **PromptCap** ([`src/openhuman/flows/tinyflows/caps/prompt.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/caps/prompt.rs)): Constructs LLM prompts based on the flow's current state, allowing the engine to generate context-aware AI requests.
- **HttpCap** ([`src/openhuman/flows/tinyflows/caps/http.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/caps/http.rs)): Performs outbound HTTP requests defined in flow nodes, handling external API integrations.
- **CodeCap** ([`src/openhuman/flows/tinyflows/caps/code.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/caps/code.rs)): Executes sandboxed scripts as part of flow progression, enabling dynamic computation steps.
- **AgentCap** ([`src/openhuman/flows/tinyflows/caps/agent.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/caps/agent.rs)): Invokes OpenHuman agent tools such as `run_workflow` and `await_workflow`, facilitating complex multi-agent orchestration.

Because these capabilities are supplied as trait objects, the host can swap implementations—for example, switching LLM providers or sandbox environments—without changing the core TinyFlows engine.

## Observability and Persistence Integration

The workflow domain tracks execution progress through dedicated observability and persistence adapters. During runtime, the engine emits `FlowProgressEvent` structures defined in [`src/openhuman/flows/tinyflows/observability.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/observability.rs), which the domain publishes to the core event bus. UI components subscribe to this bus to receive live execution updates.

State management flows through [`src/openhuman/flows/tinyflows/memory_adapter.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/memory_adapter.rs), which implements the `FlowMemory` trait used by the engine. This adapter stores flow state, checkpoints, and draft revisions, allowing the execution to resume from interruptions or maintain history for debugging purposes.

## Execution Flow: From RPC to Runtime

When a client invokes the `openhuman.flows_run` method via JSON-RPC, the integration follows a precise sequence:

1. **Schema validation** occurs in [`src/openhuman/flows/schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/schemas.rs), ensuring the request contains valid `draft_id` and input parameters.
2. **Operation handling** in [`src/openhuman/flows/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/ops.rs) creates an `EngineContext` and retrieves the stored flow definition.
3. **Engine initialization** loads the graph into `TinyFlowsEngine` from [`src/openhuman/flows/tinyflows/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/mod.rs).
4. **Node resolution** proceeds iteratively, with the engine calling `caps::agent` to invoke tools and `caps::prompt` to generate AI contexts.
5. **Side-effect execution** happens through `caps::http` and `caps::code` for external calls and computation.
6. **Progress emission** sends events through [`src/openhuman/flows/tinyflows/observability.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/observability.rs) to update listening clients.

## Practical Implementation Examples

To execute a flow programmatically from within the Rust codebase:

```rust
use openhuman_core::flows::tinyflows::{EngineContext, TinyFlowsEngine};
use openhuman_core::flows::ops::run_flow;

// Initialize the engine with default capabilities
let engine = TinyFlowsEngine::default();

// Construct context with database and service references
let ctx = EngineContext::new(&engine, /* DB, RPC client */);

// Execute the stored draft
let result = run_flow(&ctx, "draft-12345".into()).await?;
println!("Flow output: {:?}", result);

```

Client applications can trigger flows through the JSON-RPC interface:

```typescript
// Using the OpenHuman JavaScript client
const result = await coreRpcClient.call(
  "openhuman.flows_run",
  { draft_id: "draft-12345", input: {} }
);
console.log("Execution completed", result);

```

## Summary

- The workflow domain in `src/openhuman/flows/` provides RPC schema definitions in [`schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs) and operation handlers in [`ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/ops.rs) that serve as the primary integration surface.
- `TinyFlowsEngine` from [`src/openhuman/flows/tinyflows/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/mod.rs) handles pure graph execution without domain concerns, accepting an `EngineContext` for initialization.
- Capability traits in `src/openhuman/flows/tinyflows/caps/` supply the engine with LLM prompting, HTTP requests, code execution, and agent tool invocation.
- [`src/openhuman/flows/tinyflows/observability.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/observability.rs) and [`memory_adapter.rs`](https://github.com/tinyhumansai/openhuman/blob/main/memory_adapter.rs) handle event emission and state persistence, connecting execution progress to UI components and storage systems.
- This layered approach allows the TinyFlows engine to remain host-agnostic while the workflow domain manages lifecycle, persistence, and external interfaces.

## Frequently Asked Questions

### What role do the capability traits (caps) play in the TinyFlows integration?

The caps layer acts as a dependency injection mechanism that supplies the TinyFlows engine with host-specific behaviors. By implementing traits like `PromptCap`, `HttpCap`, `CodeCap`, and `AgentCap` in `src/openhuman/flows/tinyflows/caps/`, the workflow domain determines how the engine performs LLM calls, network requests, and code execution without the engine needing to know implementation details. This decoupling allows the same engine to run in different environments—development, production, or testing—simply by swapping capability implementations.

### How does the workflow domain persist flow execution state?

State persistence occurs through the `FlowMemory` trait implemented in [`src/openhuman/flows/tinyflows/memory_adapter.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/memory_adapter.rs). When the engine reaches checkpoints or completes steps, it calls methods on this trait to save current state, variables, and execution progress. The domain provides the concrete implementation backed by the core database, enabling features like resuming interrupted flows or auditing historical runs while keeping the engine itself stateless.

### Can TinyFlows operate independently of the OpenHuman RPC layer?

Yes, the TinyFlows engine functions as a pure Rust library that requires only an `EngineContext` and capability implementations to run. While [`src/openhuman/flows/schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/schemas.rs) and [`ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/ops.rs) provide the JSON-RPC interface used by external clients, internal code can invoke `run_flow` directly from [`src/openhuman/flows/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/ops.rs) or instantiate `TinyFlowsEngine` manually. This flexibility supports background job processors, embedded automation, or testing environments that bypass the RPC stack entirely.

### How does the integration support real-time UI updates during flow execution?

The observability layer in [`src/openhuman/flows/tinyflows/observability.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tinyflows/observability.rs) defines `FlowProgressEvent` structures that the engine emits at each execution step. These events propagate to the core event bus, which UI clients subscribe to via WebSocket or Server-Sent Events connections. Because the engine publishes these updates synchronously during graph traversal, interfaces can display live node activation, variable changes, and completion status without polling the database.