Introduction

Welcome to Circuit - a node-based runtime engine for building applications with computational blocks written in Rust that runs anywhere.

What is Circuit?

Circuit is a flexible, cross-platform runtime engine that allows you to create applications using a visual node-based architecture. Write your computational blocks in Rust once, and run them on Swift (iOS/macOS), Kotlin (Android), and Web/React platforms.

Key Features

Universal Blocks: Write computational blocks in Rust once, use everywhere
Declarative Language: Define blocks and flows using .block and .flow files
Cross-Platform: Run on iOS, macOS, Android, and Web (via WebAssembly)
Type-Safe: Strong typing with Rust's safety guarantees
Visual Flow: Node-based execution graphs for clear data flow
Extensible: Easy to add custom blocks for your use cases
Zero-Copy FFI: Efficient cross-language communication
Cycle Detection: Automatic validation of graph structures
Topological Execution: Optimized execution order
Comprehensive Testing: Unit, integration, and WASM tests included

Why Circuit?

Traditional cross-platform development often requires writing the same logic multiple times for different platforms. Circuit solves this by:

Write Once, Run Anywhere: Write your computational blocks in Rust and automatically use them across all platforms
Visual Programming: Define complex data flows using an intuitive node-based system
Type Safety: Leverage Rust's type system for runtime safety across all platforms
Performance: Compiled Rust code ensures optimal performance on every platform
Maintainability: Update logic in one place and deploy everywhere

Use Cases

Circuit is perfect for:

Data Processing Pipelines: Transform and process data through reusable blocks
Business Logic: Share complex business rules across mobile and web
Machine Learning: Build ML inference pipelines that work everywhere
Game Logic: Create game mechanics once, deploy to all platforms
Computational Apps: Any application with complex computational requirements

Quick Example

Here's a simple calculator flow that demonstrates Circuit's declarative syntax:

flow calculator {
    description "Simple calculator: (5 + 3) * 2 = 16"

    node const5: core.constant { value = 5 }
    node const3: core.constant { value = 3 }
    node add: math.add
    node multiply: math.multiply

    connect const5.value -> add.a
    connect const3.value -> add.b
    connect add.result -> multiply.a
}

This flow creates a calculation graph that:

Creates two constant values (5 and 3)
Adds them together
Multiplies the result by another value

Next Steps

New to Circuit? Start with the Quick Start guide
Want to understand the architecture? Read the Architecture Overview
Ready to build? Jump to Creating Custom Blocks
Integrating with a platform? Check out the Platform Integration guides

Community and Support

Circuit is actively developed and welcomes contributions. If you encounter issues or have questions:

GitHub Issues: Report bugs or request features
Documentation: This comprehensive guide covers all aspects of Circuit
Examples: Check the examples/ directory for working code samples

Let's get started building with Circuit!

Quick Start

Get up and running with Circuit in minutes!

Prerequisites

Before you begin, ensure you have:

Rust installed (1.70 or later)
Basic familiarity with Rust syntax
A text editor or IDE

Installation

1. Install Rust

If you haven't already, install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Add Circuit to Your Project

Add Circuit to your Cargo.toml:

[dependencies]
circuit-core = { path = "../circuit-core" }
circuit-lang = { path = "../circuit-lang" }

Or clone the repository:

git clone https://github.com/blankly-app/circuit.git
cd circuit

Your First Program

Let's create a simple calculator using Circuit's Rust API:

use circuit_core::{blocks::*, *};
use std::sync::Arc;

fn main() -> Result<()> {
    // Create the engine
    let mut engine = Engine::new();

    // Register built-in blocks
    engine.register_block(Arc::new(AddBlock))?;
    engine.register_block(Arc::new(MultiplyBlock))?;
    engine.register_block(Arc::new(ConstantBlock))?;

    // Create a graph
    let mut graph = Graph::new(
        "calculator".to_string(),
        "Simple Calculator".to_string()
    );

    // Add nodes
    let const5 = graph.add_node(Node::new(
        "const5".to_string(),
        "core.constant".to_string(),
        vec![("value".to_string(), Value::Int(5))].into_iter().collect(),
    ));

    let const3 = graph.add_node(Node::new(
        "const3".to_string(),
        "core.constant".to_string(),
        vec![("value".to_string(), Value::Int(3))].into_iter().collect(),
    ));

    let add = graph.add_node(Node::new(
        "add".to_string(),
        "math.add".to_string(),
        HashMap::new(),
    ));

    // Connect nodes
    graph.connect(&const5, "value", &add, "a")?;
    graph.connect(&const3, "value", &add, "b")?;

    // Load and execute
    engine.load_graph(graph)?;
    let results = engine.execute_graph("calculator")?;

    println!("Result: {:?}", results);

    Ok(())
}

Run it:

cargo run

Using the Declarative Language

Circuit's declarative language makes it even easier. Create a file calculator.flow:

flow calculator {
    description "Simple calculator: (5 + 3) * 2 = 16"

    node const5: core.constant { value = 5 }
    node const3: core.constant { value = 3 }
    node const2: core.constant { value = 2 }

    node add: math.add
    node multiply: math.multiply

    connect const5.value -> add.a
    connect const3.value -> add.b
    connect add.result -> multiply.a
    connect const2.value -> multiply.b
}

Load and execute it:

use circuit_core::*;
use circuit_lang::{parse_flow, flow_to_graph};
use std::fs;

fn main() -> Result<()> {
    let mut engine = Engine::new();

    // Register blocks (as before)
    // ...

    // Load flow file
    let source = fs::read_to_string("calculator.flow")?;
    let flow = parse_flow(&source)?;
    let graph = flow_to_graph(&flow)?;

    engine.load_graph(graph)?;
    let results = engine.execute_graph("calculator")?;

    println!("Calculator result: {:?}", results);
    Ok(())
}

Running the Examples

Circuit comes with several example flows in the examples/ directory:

# Run the calculator example
cargo run --example calculator

# Run tests to see all examples in action
cargo test -p circuit-lang --test integration_tests

Next Steps

Now that you've seen the basics, explore:

Your First Flow - A detailed walkthrough of creating flows
Architecture Overview - Understand how Circuit works
Understanding Blocks - Deep dive into blocks
The Declarative Language - Complete language reference

Common Issues

Missing Blocks

If you see "Block not found" errors, make sure you've registered all the blocks you're using:

#![allow(unused)]
fn main() {
engine.register_block(Arc::new(AddBlock))?;
engine.register_block(Arc::new(MultiplyBlock))?;
// etc.
}

Connection Errors

Port names must match exactly. Check your block definitions for the correct input/output port names.

Parse Errors

When using .flow files, ensure:

Block types are registered before loading
Syntax matches the language specification
All connections reference valid ports

Installation

This guide covers installing Circuit for different platforms and use cases.

Rust Development

Prerequisites

Rust 1.70 or later
Cargo (comes with Rust)

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Verify installation:

rustc --version
cargo --version

Using mise (optional/recommended)

If you prefer to use mise for developer tool/version management, you can use the repo-provided mise.toml and the rust-toolchain file to automatically install and pin the correct Rust version and components.

# Install mise (only if you don't have it)
curl https://mise.run | sh

# Activate mise in your shell (zsh example)
eval "$(~/.local/bin/mise activate zsh)"

# From the repository root, activate the Rust toolchain and install configured tools
cd circuit
mise use rust@1.90.0
mise install

# Verify cargo/rust version (runs inside mise environment)
mise x -- cargo --version

Note: .rust-toolchain.toml is also included and will ensure rustup uses the right channel and components if you're using rustup directly.

Clone Circuit

git clone https://github.com/blankly-app/circuit.git
cd circuit

Build All Packages

# Build all packages in release mode
cargo build --release

# Run tests to verify everything works
cargo test

# Run an example
cargo run --example calculator

Platform-Specific Installation

iOS/macOS (Swift)

Install Additional Targets

# For iOS devices (ARM64)
rustup target add aarch64-apple-ios

# For iOS Simulator (x86_64)
rustup target add x86_64-apple-ios

# For iOS Simulator (ARM64, M1/M2 Macs)
rustup target add aarch64-apple-ios-sim

# For macOS
rustup target add aarch64-apple-darwin  # Apple Silicon
rustup target add x86_64-apple-darwin   # Intel Macs

Build for iOS

# Build the FFI library for iOS
cargo build --release --target aarch64-apple-ios -p circuit-ffi

# The library will be at: target/aarch64-apple-ios/release/libcircuit_ffi.a

See the Swift Integration Guide for detailed Xcode setup.

Android (Kotlin)

Install NDK and Targets

Install Android NDK via Android Studio or standalone
Add Rust targets:

rustup target add aarch64-linux-android   # ARM64
rustup target add armv7-linux-androideabi # ARMv7
rustup target add i686-linux-android      # x86
rustup target add x86_64-linux-android    # x86_64

Configure Cargo for Android

Create or edit ~/.cargo/config.toml:

[target.aarch64-linux-android]
ar = "/path/to/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
linker = "/path/to/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android30-clang"

[target.armv7-linux-androideabi]
ar = "/path/to/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
linker = "/path/to/ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi30-clang"

Replace /path/to/ndk with your NDK installation path.

Build for Android

# Build for ARM64 (most common)
cargo build --release --target aarch64-linux-android -p circuit-ffi

# The library will be at: target/aarch64-linux-android/release/libcircuit_ffi.so

See the Kotlin Integration Guide for Android Studio setup.

Web/React (WebAssembly)

Install wasm-pack

curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

Or with cargo:

cargo install wasm-pack

Build WASM Package

cd circuit-wasm
wasm-pack build --target web --release

# Or for bundlers (webpack, vite, etc.)
wasm-pack build --target bundler --release

This creates a pkg/ directory with:

circuit_wasm_bg.wasm - The WebAssembly module
circuit_wasm.js - JavaScript bindings
circuit_wasm.d.ts - TypeScript definitions
package.json - NPM package manifest

Install in Your Web Project

cd your-web-project
npm install ../circuit/circuit-wasm/pkg

Or publish to NPM and install normally.

See the React Integration Guide for detailed web setup.

Development Tools

Optional: Install cargo-watch for Auto-rebuild

cargo install cargo-watch

Use it during development:

cargo watch -x test
cargo watch -x 'run --example calculator'

Optional: Install cargo-expand for Macro Debugging

cargo install cargo-expand

Useful for inspecting generated code:

cargo expand -p circuit-core

Optional: Install mdBook for Documentation

cargo install mdbook

Build and serve the documentation locally:

cd docs
mdbook serve --open

Verification

Run All Tests

cargo test --all

Build All Targets

# Native
cargo build --release

# iOS
cargo build --release --target aarch64-apple-ios -p circuit-ffi

# Android
cargo build --release --target aarch64-linux-android -p circuit-ffi

# WASM
cd circuit-wasm && wasm-pack build --target web

Run Examples

cargo run --example calculator

Troubleshooting

Linker Errors on macOS

If you encounter linker errors, ensure you have Xcode command line tools:

xcode-select --install

Android NDK Not Found

Ensure ANDROID_NDK_HOME is set:

export ANDROID_NDK_HOME=/path/to/android-ndk

Add to your .bashrc or .zshrc for persistence.

WASM Build Fails

Ensure you have the wasm32 target:

rustup target add wasm32-unknown-unknown

And install wasm-bindgen-cli:

cargo install wasm-bindgen-cli

Next Steps

Quick Start - Create your first Circuit application
Architecture Overview - Understand how Circuit works
Platform Integration - Integrate with your platform

Your First Flow

This tutorial will walk you through creating your first Circuit flow from scratch.

What You'll Build

We'll create a temperature converter that converts Celsius to Fahrenheit using the formula:

F = (C × 9/5) + 32

Step 1: Create the Flow File

Create a new file called temp_converter.flow:

flow temp_converter {
    description "Converts Celsius to Fahrenheit"

    // Input temperature in Celsius
    node celsius: core.constant {
        value = 25
    }

    // Constants for the formula
    node nine: core.constant {
        value = 9
    }

    node five: core.constant {
        value = 5
    }

    node thirtytwo: core.constant {
        value = 32
    }

    // Calculations: (C × 9 / 5) + 32
    node multiply: math.multiply
    node divide: math.multiply  // We'll use multiply with 1/5 = 0.2
    node add: math.add

    // Connect the graph
    connect celsius.value -> multiply.a
    connect nine.value -> multiply.b
    connect multiply.result -> divide.a
    connect five.value -> divide.b
    connect divide.result -> add.a
    connect thirtytwo.value -> add.b

    // Output the final result
    output add.result
}

Step 2: Understanding the Flow

Let's break down what this flow does:

Constants: We define constant values for:
- celsius (25) - the input temperature
- nine (9) - part of the conversion formula
- five (5) - part of the conversion formula
- thirtytwo (32) - the offset in the formula
Operations: We create three math operation nodes:
- multiply - multiplies Celsius by 9
- divide - divides by 5
- add - adds 32
Connections: We wire the nodes together to form the calculation pipeline
Output: We expose the final result from the add node

Step 3: Load and Execute

Create a Rust program to execute the flow:

use circuit_core::*;
use circuit_core::blocks::*;
use circuit_lang::{parse_flow, flow_to_graph};
use std::sync::Arc;
use std::fs;

fn main() -> Result<()> {
    // Create engine and register blocks
    let mut engine = Engine::new();
    engine.register_block(Arc::new(AddBlock))?;
    engine.register_block(Arc::new(MultiplyBlock))?;
    engine.register_block(Arc::new(ConstantBlock))?;

    // Load the flow file
    let source = fs::read_to_string("temp_converter.flow")?;
    let flow = parse_flow(&source)?;
    let graph = flow_to_graph(&flow)?;

    // Execute
    let graph_id = graph.id.clone();
    engine.load_graph(graph)?;
    let results = engine.execute_graph(&graph_id)?;

    // Print results
    for (node_id, outputs) in results {
        println!("Node {}: {:?}", node_id, outputs);
    }

    Ok(())
}

Step 4: Run It

cargo run

You should see output showing the intermediate calculations and the final result (25°C = 77°F).

Step 5: Make It Interactive

Now let's make it easier to change the input. Modify your Rust program:

use std::io::{self, Write};

fn main() -> Result<()> {
    // ... (setup code as before)

    // Get temperature from user
    print!("Enter temperature in Celsius: ");
    io::stdout().flush()?;

    let mut input = String::new();
    io::stdin().read_line(&mut input)?;
    let celsius: f64 = input.trim().parse()
        .map_err(|_| CircuitError::InvalidInput("Invalid number".to_string()))?;

    // Modify the constant node's configuration
    // (In a real app, you'd modify the graph before loading)

    // ... (execution code)

    Ok(())
}

Next Steps

Congratulations! You've created your first Circuit flow. Here's what to explore next:

Create Custom Blocks

Instead of using just constants and math operations, create custom blocks:

block conversion.celsius_to_fahrenheit {
    description "Converts Celsius to Fahrenheit"

    input celsius: Number {
        description "Temperature in Celsius"
    }

    output fahrenheit: Number {
        description "Temperature in Fahrenheit"
    }

    execute {
        fahrenheit = (celsius * 9 / 5) + 32
    }
}

Add More Features

Extend your temperature converter:

Support both directions (C→F and F→C)
Add Kelvin conversion
Add input validation
Create a visual display

Learn More About Flows

Creating Flows - Detailed flow guide
The Declarative Language - Complete syntax reference
Built-in Blocks - Available blocks

Try the Examples

Check out the example flows in examples/flows/:

cargo test -p circuit-lang --test integration_tests

Troubleshooting

"Block not found" error

Make sure all blocks used in your flow are registered:

#![allow(unused)]
fn main() {
engine.register_block(Arc::new(AddBlock))?;
engine.register_block(Arc::new(MultiplyBlock))?;
engine.register_block(Arc::new(ConstantBlock))?;
}

Connection errors

Verify port names match exactly. Use:

.value for constant block outputs
.a and .b for math block inputs
.result for math block outputs

Parse errors

Check your .flow syntax:

Node definitions need node id: type { config }
Connections need connect from.port -> to.port
All statements should be inside the flow { } block

Architecture Overview

Understanding Circuit's architecture will help you build better applications and debug issues more effectively.

High-Level Architecture

Circuit consists of four main layers:

┌─────────────────────────────────────────────────────┐
│         Platform Layer (Swift/Kotlin/JS)            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐  │
│  │     iOS      │  │   Android    │  │   Web    │  │
│  └──────────────┘  └──────────────┘  └──────────┘  │
└─────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────┐
│          FFI/WASM Bindings Layer                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐  │
│  │ circuit-ffi  │  │ circuit-ffi  │  │circuit-  │  │
│  │   (Swift)    │  │  (Kotlin)    │  │  wasm    │  │
│  └──────────────┘  └──────────────┘  └──────────┘  │
└─────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────┐
│              Language Layer                         │
│              ┌──────────────┐                       │
│              │ circuit-lang │                       │
│              │   Parser &   │                       │
│              │  Converter   │                       │
│              └──────────────┘                       │
└─────────────────────────────────────────────────────┘
                         │
┌─────────────────────────────────────────────────────┐
│               Core Runtime Engine                   │
│              ┌──────────────┐                       │
│              │ circuit-core │                       │
│              │   Engine,    │                       │
│              │  Blocks,     │                       │
│              │   Graphs     │                       │
│              └──────────────┘                       │
└─────────────────────────────────────────────────────┘

Core Components

1. circuit-core: The Runtime Engine

The heart of Circuit, circuit-core provides:

Blocks

The fundamental unit of computation. Each block:

Has inputs (data it receives)
Has outputs (data it produces)
Has configuration (parameters that customize behavior)
Implements an execute method (the actual computation)

#![allow(unused)]
fn main() {
pub trait Block: Send + Sync {
    fn metadata(&self) -> BlockMetadata;
    fn execute(&self, context: BlockContext) -> Result<HashMap<String, Value>>;
    fn validate(&self, _config: &HashMap<String, Value>) -> Result<()> { Ok(()) }
}
}

Graphs

A directed acyclic graph (DAG) representing data flow:

Nodes: Instances of blocks with unique IDs
Connections: Data paths between node ports
Cycle Detection: Ensures no circular dependencies
Validation: Checks that all connections are valid

Engine

The execution runtime that:

Registers blocks (makes them available)
Loads graphs (prepares them for execution)
Executes graphs in topological order
Routes data between connected nodes
Returns final output values

Values

Type-safe data containers supporting:

Null, Bool, Int, Float, String
Array, Object (nested structures)
Bytes (binary data)
Conversion and serialization via serde

2. circuit-lang: The Declarative Language

Provides a human-friendly way to define blocks and flows:

Parser

Uses Pest grammar to parse .block and .flow files into AST (Abstract Syntax Tree).

Converter

Transforms AST into executable Graph objects that the engine can run.

Benefits

Declarative: Describe what you want, not how to build it
Readable: Clear syntax for non-programmers
Maintainable: Easy to modify flows without recompiling

3. circuit-ffi: Native Platform Bridge

C-compatible FFI layer for iOS and Android:

C API: Simple functions for create, load, execute, destroy
Memory Management: Safe handling of strings and pointers
Error Handling: Proper error propagation across FFI boundary
Thread Safety: Uses lazy_static for global engine registry

Swift and Kotlin wrappers provide idiomatic APIs on top of the C layer.

4. circuit-wasm: Web Assembly Bridge

WebAssembly bindings for browser and Node.js:

wasm-bindgen: Automatic JavaScript bindings
Zero-Copy: Efficient data transfer between JS and Rust
TypeScript: Full type definitions included
Promise-based: Async/await friendly API

Data Flow

Here's how data flows through a Circuit application:

1. Define Flow (.flow file or Rust code)
   │
   ├─> Defines nodes (block instances)
   ├─> Defines connections (data paths)
   └─> Defines configuration (block parameters)

2. Parse/Convert (circuit-lang)
   │
   └─> Converts to Graph object

3. Load Graph (Engine)
   │
   ├─> Validates graph structure
   ├─> Checks for cycles
   └─> Computes topological order

4. Execute Graph (Engine)
   │
   ├─> Executes nodes in topological order
   ├─> Routes data through connections
   └─> Collects final outputs

5. Return Results
   │
   └─> HashMap<String, HashMap<String, Value>>

Topological Execution

Circuit executes nodes in topological order, ensuring:

A node only executes after all its dependencies
Data flows in the correct direction
No deadlocks or circular dependencies

Example

For this flow:

flow example {
    node a: core.constant { value = 1 }
    node b: core.constant { value = 2 }
    node c: math.add
    node d: math.multiply

    connect a.value -> c.a
    connect b.value -> c.b
    connect c.result -> d.a
}

Execution order:

a and b execute first (no dependencies)
c executes next (depends on a and b)
d executes last (depends on c)

Memory Model

Rust Side

Blocks: Arc<dyn Block> - Thread-safe, shared references
Graphs: Owned by Engine, stored in HashMap
Values: Cloned when passed between nodes (cheap for small values)

FFI Boundary

Strings: Converted between Rust String and C char*
Pointers: Engine handles stored in global registry
Memory Safety: Rust manages all allocations

WASM Boundary

Values: Serialized as JSON across boundary
Optimization: Uses wasm-bindgen for efficient marshaling
Memory: WASM linear memory managed by Rust

Error Handling

Circuit uses Rust's Result type throughout:

#![allow(unused)]
fn main() {
pub type Result<T> = std::result::Result<T, CircuitError>;

pub enum CircuitError {
    BlockNotFound(String),
    GraphNotFound(String),
    InvalidInput(String),
    InvalidConnection(String),
    CycleDetected,
    ExecutionError(String),
    ParseError(String),
}
}

Errors propagate through the stack and can be caught at the platform layer.

Performance Characteristics

Graph Loading: O(N + E) where N = nodes, E = edges
Topological Sort: O(N + E)
Execution: O(N × B) where B = average block execution time
Data Flow: Cloning overhead for Values (typically small)

Optimization Opportunities

Lazy Evaluation: Only execute nodes needed for requested outputs
Parallelization: Execute independent nodes concurrently
Caching: Memoize block results for repeated inputs
Streaming: Support streaming data for large datasets

These are future roadmap items.

Thread Safety

Engine: Not thread-safe; use one per thread or protect with Mutex
Blocks: Must be Send + Sync (thread-safe)
Graphs: Immutable after loading (safe to share)
Values: Cloned between nodes (no shared mutation)

Next Steps

Understanding Blocks - Deep dive into blocks
The Graph Engine - Engine internals
Creating Custom Blocks - Build your own blocks

Understanding Blocks

Note: This section is under development. Check back soon for detailed documentation.

Overview

This page will cover Understanding Blocks in detail.

Coming Soon

Detailed documentation for this topic is being written.

In the Meantime

Check out the Getting Started guide
Explore the examples directory
Read the source code in the repository

Type	Description	Example Values
`Number`	Floating-point numbers	`42`, `3.14`, `-10.5`
`String`	Text strings	`"hello"`, `"world"`
`Bool`	Boolean values	`true`, `false`
`Array`	Ordered lists	`[1, 2, 3]`, `["a", "b"]`
`Object`	Key-value maps	`{"key": "value"}`
`Bytes`	Binary data	Raw byte arrays
`Any`	Any type	Any of the above
`Null`	Null value	`null`

Circuit Documentation