> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> A high-level view of the BlobHub stack — surfaces, platform, and Blob Type engines.

Where [Concepts](/general/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.

```mermaid theme={null}
flowchart TB
    subgraph CLIENTS["Client Surfaces"]
        direction LR
        WEB["Web Application<br/>blobhub.io"]
        SDK["Python SDK<br/>pip install blobhub"]
        APP["Your Application"]
    end

    subgraph APIS["API Layer"]
        direction LR
        REST["REST API<br/>api.blobhub.io/v1/"]
        WS["WebSocket API<br/>realtime.blobhub.io/v1/"]
    end

    subgraph CORE["Platform Core"]
        direction LR
        ORGS["Organizations<br/>&amp; Access Control"]
        BLOBS["Blobs<br/>&amp; Revisions"]
        META["Metadata<br/>&amp; Operations"]
        ORGS ~~~ BLOBS ~~~ META
    end

    subgraph ENGINES["Blob Type Engines"]
        direction LR
        WF["Workflow Engine<br/>Definitions · Sessions · Executions"]
        SCH["Scheduler Engine<br/>Cron · One-time · History"]
        ONNX["ONNX Engine<br/>Upload · Describe · Download"]
        WF ~~~ SCH ~~~ ONNX
    end

    WEB --> REST
    WEB --> WS
    SDK --> REST
    APP --> REST
    APP --> WS

    REST --> CORE
    WS --> CORE

    CORE --> ENGINES

    classDef layer fill:#0D9373,stroke:#07C983,stroke-width:1px,color:#ffffff;
    class WF,SCH,ONNX layer;
```

## Client Surfaces

BlobHub exposes the same platform through several complementary entry points:

* **Web Application** ([blobhub.io](https://blobhub.io/)) — visual management, interactive workflow
  playground, real-time monitoring.
* **Python SDK** ([`pip install blobhub`](/sdk/introduction)) — 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](/rest-api/introduction) 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](/web-socket/introduction) 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.

```mermaid theme={null}
flowchart LR
    C["Client"]
    C -->|"request / response"| REST["REST API<br/>api.blobhub.io/v1/"]
    C <-->|"subscribe / stream"| WS["WebSocket API<br/>realtime.blobhub.io/v1/"]

    REST --> PLAT["Platform"]
    WS --> PLAT
```

## 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:

| Engine        | What it runs                                | Key primitives                                   |
| :------------ | :------------------------------------------ | :----------------------------------------------- |
| **Workflow**  | Component-based executable graphs           | Definition, Session, Execution, Execution Events |
| **Scheduler** | Time-based triggers for Workflow Executions | Schedule (one-time or cron), Execution history   |
| **ONNX**      | ML model hosting                            | Multipart upload, describe, presigned download   |

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](/blob-types/introduction) for the full reference of each engine.

## How a Request Flows

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

```mermaid theme={null}
flowchart LR
    APP(["Your App"])
    APP -->|"POST /v1/.../executions"| REST["REST API"]
    REST -->|"authorize"| CORE["Platform Core"]
    CORE -->|"dispatch"| WFE["Workflow Engine"]
    WFE -->|"emit events"| WS["WebSocket API"]
    WS -->|"stream"| APP
```

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

<CardGroup cols={2}>
  <Card title="Concepts" icon="book" href="/general/concepts">
    The primitives the architecture is built around.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/general/quickstart">
    Exercise the full stack end-to-end in a few minutes.
  </Card>

  <Card title="REST API" icon="code" href="/rest-api/introduction">
    The request/response surface of the platform.
  </Card>

  <Card title="WebSocket API" icon="bolt" href="/web-socket/introduction">
    The real-time event stream surface.
  </Card>
</CardGroup>