# OpenHuman Project Structure: How the Rust Core and React/Tauri Desktop Shell Work Together

> Explore the OpenHuman project structure. Learn how the Rust core and React Tauri desktop shell collaborate using an in-process HTTP-JSON-RPC bridge for efficient data exchange.

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

---

**The OpenHuman project uses a dual-layer architecture that isolates high-performance business logic in a Rust core from a modern React interface, packaging them together as a Tauri desktop application that communicates via an in-process HTTP-JSON-RPC bridge.**

OpenHuman is an open-source AI agent platform designed as a dual-layer application. Understanding the OpenHuman project structure reveals how the repository cleanly separates the performance-critical Rust business logic from the React-based user interface while maintaining tight integration through a low-latency RPC mechanism.

## Repository Layout: Core vs. Shell

The repository is deliberately partitioned into distinct directories. This separation ensures the core can function as a standalone binary or library while the desktop shell provides a native user experience.

### The Rust Core (`src/`)

The `src/` directory at the repository root implements all domain logic including agent behavior, memory management, tools, and security features. It provides **JSON-RPC** and **CLI** interfaces for external interaction.

- **Primary Entry Point**: [`src/main.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/main.rs) builds the `openhuman-core` binary.
- **Build Command**: `cargo build --bin openhuman-core`
- **Key Components**: Domain controllers, provider abstractions (OpenAI-compatible APIs), and the `Harness` interface defined in [`src/openhuman/harness.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/harness.rs).

### The React/Tauri Shell (`app/`)

The `app/` directory contains the pnpm workspace `openhuman-app`, which bundles a Vite + React frontend with a Tauri host process.

- **React Entry**: [`app/src/main.tsx`](https://github.com/tinyhumansai/openhuman/blob/main/app/src/main.tsx) initializes the user interface.
- **Tauri Host**: [`app/src-tauri/src/main.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/main.rs) manages the native window and core process lifecycle.
- **RPC Client**: [`app/src/services/coreRpcClient.ts`](https://github.com/tinyhumansai/openhuman/blob/main/app/src/services/coreRpcClient.ts) exposes `coreRpcClient` for frontend-to-core communication.

### Documentation (`gitbooks/`)

Architecture overviews and design diagrams reside in [`gitbooks/developing/architecture.md`](https://github.com/tinyhumansai/openhuman/blob/main/gitbooks/developing/architecture.md), providing high-level visualizations of the Rust-Tauri integration.

## Core-Shell Communication Architecture

The two layers communicate through an **in-process HTTP-JSON-RPC server** rather than traditional inter-process communication. This approach eliminates network overhead and ensures deterministic, low-latency behavior.

The core launches as a Tokio task via `core_process::CoreProcessHandle` inside the Tauri host. It exposes an HTTP server on a dynamic local port (`http://127.0.0.1:<port>/rpc`) using the method `run_server_embedded_with_ready()`, which accepts a one-time bearer token via the `rpc_token: Some(_)` parameter.

The React frontend retrieves this token through the Tauri command `core_rpc_token`, then instantiates the `coreRpcClient` (backed by `relay_http_rpc`) to invoke core methods. Environment variables provide alternative access patterns: `OPENHUMAN_CORE_TOKEN` for CLI or Docker usage, and `OPENHUMAN_CORE_REUSE_EXISTING=1` to allow external debuggers to attach to running core instances.

## Development Workflow and Build Commands

Building the OpenHuman project requires coordinating Rust and Node.js toolchains. The root [`package.json`](https://github.com/tinyhumansai/openhuman/blob/main/package.json) defines pnpm scripts that orchestrate both layers.

Compile the core library and binary:

```bash
cargo build --manifest-path Cargo.toml --bin openhuman-core

```

Run the core in standalone CLI mode for debugging:

```bash
./target/debug/openhuman-core serve

```

Start the full desktop development environment (Vite dev server + Tauri host):

```bash
pnpm dev:app

```

Build a production desktop bundle respecting Cargo feature gates:

```bash
pnpm build

```

The Tauri shell respects the same **Cargo feature gates** as the core, ensuring compile-time domain gating (e.g., `voice`, `web3`) applies uniformly to both layers.

## Extending the Architecture

Adding functionality requires coordinated changes across both layers.

### Adding a Domain to the Rust Core

New domains follow a modular pattern under `src/openhuman/`. After implementing schemas and controllers in a new directory (e.g., `src/openhuman/example_domain/`), register them in [`src/core/all.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs):

```rust
DomainGroup::Example => {
    all_example_controller_schemas(),
    all_example_controllers(),
}

```

Reference the domain's [`README.md`](https://github.com/tinyhumansai/openhuman/blob/main/README.md) at [`src/openhuman/example_domain/README.md`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/example_domain/README.md) for specific implementation guidelines.

### Exposing a New UI Route

Frontend routes are defined in [`app/src/AppRoutes.tsx`](https://github.com/tinyhumansai/openhuman/blob/main/app/src/AppRoutes.tsx) using standard React Router syntax:

```tsx
<Route path="/example" element={<ExamplePage />} />

```

## Code Examples

### Initializing the Core from Rust

The `Harness` builder pattern in [`src/openhuman/harness.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/harness.rs) provides the primary interface for embedding the core:

```rust
use openhuman_core::Harness;

let harness = Harness::builder()
    .provider(openhuman_core::provider::Provider::openai_compatible(
        "https://api.openai.com/v1", "sk-…"
    ))
    .workspace(openhuman_core::Workspace::Ephemeral)
    .access(openhuman_core::Access::full())
    .backend_url("https://api.tinyhumans.ai")
    .build()
    .await?;

let result = harness.run("Summarize the repository structure.").await?;
println!("{}", result);

```

### Invoking Core Methods from React

The frontend uses `coreRpcClient` from [`app/src/services/coreRpcClient.ts`](https://github.com/tinyhumansai/openhuman/blob/main/app/src/services/coreRpcClient.ts) to communicate with the embedded core:

```tsx
import { coreRpcClient } from '@/services/coreRpcClient';

async function askCore(prompt: string) {
  const response = await coreRpcClient.call('openhuman.agent_turn', {
    prompt,
    session_id: '',
  });
  return response.output;
}

```

## Key Configuration Files

Several files define the integration boundaries between layers:

- **[`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml)** – Defines the core crate, dependencies, and feature gates (e.g., `voice`, `web3`) that propagate to the Tauri build.
- **[`src/main.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/main.rs)** – Builds the `openhuman-core` binary and registers all domain controllers.
- **[`app/package.json`](https://github.com/tinyhumansai/openhuman/blob/main/app/package.json)** – Configures the pnpm workspace and defines npm scripts (`dev`, `dev:app`, `build`).
- **[`app/src-tauri/src/main.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/main.rs)** – Implements the Tauri host, creates the in-process core task, and registers Tauri commands including `core_rpc_token`.
- **[`gitbooks/developing/architecture.md`](https://github.com/tinyhumansai/openhuman/blob/main/gitbooks/developing/architecture.md)** – Contains the high-level architecture diagram describing the Rust-Tauri integration.

## Summary

- The **Rust core** in `src/` provides the business logic engine as a library and standalone binary, accessible via JSON-RPC.
- The **React/Tauri shell** in `app/` packages the UI as a native desktop application using Vite for the frontend and Tauri for the host process.
- **Communication** occurs through an in-process HTTP-JSON-RPC bridge (`relay_http_rpc`) using a bearer token passed via `run_server_embedded_with_ready()`.
- **Development** requires both `cargo` for the Rust layer and `pnpm` for the Node.js/Tauri layer, with feature gates synchronized across both.
- The architecture supports standalone core execution (`cargo run --bin openhuman-core`) for server-side or testing scenarios independent of the desktop UI.

## Frequently Asked Questions

### How does the React frontend communicate with the Rust core?

The React frontend communicates through an in-process HTTP-JSON-RPC server. The Tauri host starts the core as a Tokio task (`core_process::CoreProcessHandle`) which exposes `http://127.0.0.1:<port>/rpc`. The React application retrieves a bearer token via the Tauri command `core_rpc_token`, then uses `coreRpcClient` to invoke methods. This design eliminates network transport latency while maintaining language isolation.

### Can the Rust core run independently of the Tauri desktop application?

Yes. The core can be compiled and executed as a standalone binary using `cargo run --bin openhuman-core` or started in server mode with `./target/debug/openhuman-core serve`. This standalone mode supports CLI usage, Docker containers, and external debugging via the `OPENHUMAN_CORE_REUSE_EXISTING=1` environment variable.

### What development commands are needed to build both layers?

Use `cargo build --bin openhuman-core` to compile the Rust layer. For the desktop shell, use `pnpm dev:app` to start the development server or `pnpm build` to create production bundles. The root [`package.json`](https://github.com/tinyhumansai/openhuman/blob/main/package.json) orchestrates these commands, and the Tauri build process respects Cargo feature flags defined in [`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml).

### How do I add new functionality to both the core and UI?

To extend the system, create a new domain module under `src/openhuman/` with schemas and controllers, then register it in [`src/core/all.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs). For the UI, add routes in [`app/src/AppRoutes.tsx`](https://github.com/tinyhumansai/openhuman/blob/main/app/src/AppRoutes.tsx) and implement corresponding React components. Both changes respect the same feature gates, ensuring consistent availability of functionality across the core-shell boundary.