Architecture

Where Concepts describes the primitives of BlobHub, this page describes the system — the layers that sit between a user or application and those primitives.

​

The Big Picture

BlobHub is organized into three layers: client surfaces users and applications talk to, a unified platform core that stores and versions everything, and specialized Blob Type engines that run on top of the core.

​

Client Surfaces

BlobHub exposes the same platform through several complementary entry points:

• Web Application (blobhub.io) — visual management, interactive workflow playground, real-time monitoring.
• Python SDK (pip install blobhub) — a thin, idiomatic wrapper around the REST API for use in scripts, applications, and notebooks.
• Your Application — any HTTP client in any language, using the REST and WebSocket APIs directly.

All three surfaces speak the same API and see the same data. There is no “UI-only” feature and no “API-only” feature.

​

The API Layer

The API layer is split by interaction style, not by resource type.

​

REST API

The REST API is the primary programmatic surface. It is request/response, versioned under /v1/, and organized around the core primitives — Users, Organizations, Blobs, Revisions, Metadata, API Keys, Members, Credentials, and Operations — plus Blob-type-specific endpoints for Workflow, Scheduler, and ONNX. Use it for everything that maps naturally onto “read / write / list / delete this resource”.

​

WebSocket API

The WebSocket API is the real-time surface. Clients open a single authenticated connection and subscribe to event streams — Workflow Execution Events, Session Events, state changes — which would be expensive or impossible to poll. Use it when you need to react to platform events as they happen.

​

Platform Core

Underneath both APIs is a single platform core that implements the primitives shared by every Blob Type:

• Organizations and Access Control — the container and permission boundary for everything else. Members, API Keys, and Credentials all attach here.
• Blobs and Revisions — typed, versioned objects and their Draft → Commit → Snapshot lifecycle.
• Metadata and Operations — key/value records on Blobs and Revisions, plus the uniform Operations interface for tracking asynchronous work.

Because these primitives are shared, every Blob Type automatically inherits versioning, access control, metadata, and async operation tracking. A new Blob Type only has to define its own content and engine.

​

Blob Type Engines

Sitting on top of the platform core are the specialized engines that give each Blob Type its behavior: Engines compose — the Scheduler engine, for example, fires Workflow Executions. This composition is possible precisely because both are built on the same Organization / Blob / Revision substrate. See Blob Types for the full reference of each engine.

​

How a Request Flows

A typical “run a workflow” request exercises every layer in the stack:

1. Your application calls the REST API to start an Execution.
2. The platform core authorizes the request against the Organization, Blob, and caller’s API Key.
3. The Workflow engine picks up the Execution and begins running components.
4. Execution Events are emitted to the WebSocket API.
5. Your application — already subscribed — receives the live stream of events.

​

Design Principles

A few principles shape the architecture and are worth keeping in mind when you design against BlobHub:

• One primitive, many engines. Every Blob Type reuses the same versioning, access control, and metadata machinery. You should not need a different mental model per type.
• Versioned by default. Every change to a Blob produces a Revision. There is no “save” that silently overwrites history.
• Programmable end-to-end. Every UI action maps to a REST call. Anything you can click, you can script.
• Real-time where it matters. Long-running and event-heavy interactions are surfaced over WebSocket so that clients never have to poll for what is essentially a push problem.

​

Next Steps