Developers

Architecture (Mobile App)

Custom Butlers run inside the Life Butler mobile app in a WebView. All communication between the Butler and the host app goes through a JS Bridge. For API calls, Butlers use an event-driven architecture: they emit request events, and Butler Core handles the actual HTTP requests. Custom Butlers never make direct network connections; all API calls go through Butler Core, which provides centralized monitoring, rate limiting, and error handling.

Flow

1. Custom Butler (WebView) – Third-party Butler UI and logic run in an in-app WebView (HTML/JS). No direct network or device APIs.
2. JS Bridge – The only channel between the WebView and the app. The Butler calls bridge methods (e.g. requestData, callAPI, getAuthToken); the app invokes JS in the WebView (e.g. events, responses).
3. Butler Core – Handles all API calls via an event-driven architecture. When a Butler needs to make an API call, it emits an api.request event. Butler Core performs the actual HTTP request, applies rate limiting and authentication, implements retry logic, and emits an api.response event back to the Butler. This centralizes monitoring and ensures consistent error handling.
4. Native App Layer – Handles auth, storage, and network infrastructure. Butler Core uses the native layer to perform HTTPS requests to external APIs and Life Butler backend.
5. Life Butler Backend APIs – All server access from Custom Butlers is done through these APIs (data, auth, server-side actions). The mobile app is the only client that talks to the backend on behalf of the Butler.
6. Third-Party Butler Server – A backend run by the Butler developer. It communicates with Life Butler’s backend over HTTPS (server-to-server) for webhooks, server-side logic, or syncing. All integration with Life Butler goes through our APIs; the third-party server does not talk directly to the mobile app.

Summary

Event-Driven API Architecture

Butlers don’t make API calls directly. Instead, they emit events requesting API calls, and Butler Core handles the actual HTTP requests. This event-driven architecture provides better latency, centralized monitoring, rate limiting, and consistent error handling.

How It Works

1. Butler emits request event – When your Butler needs to make an API call, it emits an api.request event with the URL, method, headers, and body. The Butler never touches the network directly.
2. Butler Core handles HTTP – Butler Core listens for request events, performs the actual HTTP call, applies rate limiting, adds authentication headers, and implements retry logic with exponential backoff.
3. Response event emitted – When the HTTP request completes, Butler Core emits an api.response event with the response data, status code, and any errors.
4. Logging queued asynchronously – All API calls are logged via a queue that batches logs and sends them to the backend server. Logging doesn’t block the API response, ensuring low latency.
5. Butler receives response – Your Butler receives the response event and processes the data. The SDK abstracts away the event system, so you use a simple API interface.

Benefits

// In your Butler code
import { api } from '@lifebutler/sdk';

// Make an API call - SDK handles events internally
const response = await api.request({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: { 'Authorization': 'Bearer ...' }
});

// SDK automatically:
// - Emits request event
// - Waits for response event
// - Returns response data
// - Throws errors on failure

Principles

Core Features Your Butler Can Use

Life Butler provides core features that all Butlers can integrate with. These are built into the platform and accessible through the JS Bridge.

APIs

Butlers integrate via the Data Access API and follow a clear lifecycle. Full API reference and SDK docs are coming soon.

UI guidelines

Butlers run inside the Life Butler shell. Follow these guidelines so your Butler feels native and consistent.