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

# Concepts

> Key terms and concepts from the BlobHub universe

This page is a tour of the primitives that make up BlobHub. Read it top to bottom and you will have a complete
mental model of how the platform is organized.

## Organizations and Blobs

A **Blob** is the central primitive in BlobHub. It represents a typed, versioned unit of data that users
store, evolve, and interact with.

Blobs are grouped into **Organizations**. An Organization is both a container and an access boundary — it
owns a collection of Blobs and defines who can see or modify them.

```mermaid theme={null}
flowchart LR
    U1([User A])
    U2([User B])
    U3([User C])

    subgraph ORG1["Organization · acme"]
        B1[/"Blob · pipeline"/]
        B2[/"Blob · forecast-model"/]
        B3[/"Blob · nightly-schedule"/]
    end

    subgraph ORG2["Organization · research"]
        B4[/"Blob · dataset-prep"/]
        B5[/"Blob · classifier"/]
    end

    U1 --> ORG1
    U2 --> ORG1
    U2 --> ORG2
    U3 --> ORG2
```

Every Blob has a stable identifier, an owning Organization, a **Blob Type**, and a sequence of **Revisions**
that record how the Blob has evolved over time.

## Blob Types

The Blob Type chosen at creation time determines a Blob's internal data structure, its storage semantics,
and the set of operations available on it. BlobHub currently offers three primary Blob Types:

```mermaid theme={null}
flowchart TB
    BLOB[/"Blob"/]
    BLOB --> WF["<b>Workflow</b><br/>Executable<br/>component graphs"]
    BLOB --> SCH["<b>Scheduler</b><br/>Time-based<br/>workflow triggers"]
    BLOB --> ONNX["<b>ONNX</b><br/>Versioned ML<br/>model hosting"]

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

* **Workflow** Blobs describe and execute component-based backend workflows, with sessions, executions, and
  real-time execution events.
* **Scheduler** Blobs hold collections of time-based schedules that trigger workflow executions — either once
  or on a recurring cron cadence.
* **ONNX** Blobs host Open Neural Network Exchange machine learning models, with secure multipart upload and
  presigned downloads.

See [Blob Types](/blob-types/introduction) for the full reference of each type.

## Revisions and the Revision Lifecycle

A **Revision** is a point-in-time checkpoint of a Blob. Every meaningful change to a Blob produces a new
Revision, and every Revision moves through the same three-stage lifecycle.

```mermaid theme={null}
flowchart LR
    DRAFT(["<b>Draft</b><br/>mutable<br/>work in progress"])
    COMMIT(["<b>Commit</b><br/>sealed<br/>immutable content"])
    SNAPSHOT(["<b>Snapshot</b><br/>published<br/>addressable version"])

    DRAFT -->|commit| COMMIT
    COMMIT -->|snapshot| SNAPSHOT
    SNAPSHOT -.->|new draft| DRAFT

    classDef draft fill:#FEF3C7,stroke:#D97706,color:#92400E;
    classDef commit fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A;
    classDef snap fill:#D1FAE5,stroke:#0D9373,color:#064E3B;
    class DRAFT draft;
    class COMMIT commit;
    class SNAPSHOT snap;
```

* **Draft** — the Revision is open for edits. Most write operations target Drafts.
* **Commit** — the Revision's content is frozen and becomes immutable, but it is not yet a published version.
* **Snapshot** — the Revision is published and becomes a stable, addressable version of the Blob that other
  systems can safely depend on.

Because each Snapshot is immutable and addressable, rolling back to any previous version of a Blob is always
a safe operation.

## Metadata

Both **Blobs** and **Revisions** can carry **Metadata** — arbitrary key/value records attached to the object.
Metadata is a first-class concept with its own operations (create, resolve, get, update, delete) and is useful
for tagging, categorization, and storing integration-specific state alongside a Blob or Revision.

```mermaid theme={null}
flowchart LR
    BLOB[/"Blob"/]
    BLOB --> BM["Blob Metadata<br/>(key → value)"]
    BLOB --> R1[/"Revision · 1"/]
    BLOB --> R2[/"Revision · 2"/]
    R1 --> RM1["Revision Metadata<br/>(key → value)"]
    R2 --> RM2["Revision Metadata<br/>(key → value)"]
```

## Access Control

BlobHub offers flexible privacy controls layered on top of Organizations and Blobs.

* **Private** Blobs are visible only to designated members and API key holders.
* **Public** Blobs are visible to all BlobHub users.
* **Members** grant individual users access to an Organization or a specific Blob.
* **API Keys** grant programmatic read/write access — scoped to an Organization or an individual Blob.
* **Credentials** are stored secrets that Blobs (for example, Workflow components) can reference when calling
  external systems.

```mermaid theme={null}
flowchart LR
    subgraph CONSUMERS["Consumers"]
        direction TB
        USERS([Users])
        APPS([Applications])
    end

    subgraph AUTH["Access Grants"]
        direction TB
        MEM["Members<br/>(per user)"]
        KEYS["API Keys<br/>(per app)"]
    end

    subgraph RESOURCE["Protected Resource"]
        direction TB
        ORG["Organization"]
        BLOB[/"Blob"/]
        CREDS["Credentials<br/>(secrets used by Blob)"]
        ORG --- BLOB
        BLOB --- CREDS
    end

    USERS --> MEM --> ORG
    APPS --> KEYS --> ORG
    APPS --> KEYS --> BLOB
```

Read access, write access, and administrative access are all distinguished, and grants can be attached at
either the Organization or the individual Blob level.

## Workflow Primitives

Workflow Blobs introduce a small set of additional primitives that describe how workflows are defined and
executed.

```mermaid theme={null}
flowchart LR
    DEF[/"Definition<br/>(component graph)"/]
    SESS[/"Session<br/>(stateful run context)"/]
    EXEC[/"Execution<br/>(one run of a definition)"/]
    EVT["Execution Events<br/>(real-time updates)"]

    DEF -->|instantiated in| SESS
    SESS -->|produces| EXEC
    EXEC -->|emits| EVT
```

* **Definition** — the JSON blueprint describing the components of a workflow and the connections between
  them. Stored as the content of a Workflow Blob's Revision.
* **Session** — a stateful context in which a Definition runs. Sessions hold shared state, uploaded objects,
  and a history of executions.
* **Execution** — a single invocation of a Definition inside a Session.
* **Execution Events** — the real-time stream of events emitted while an Execution runs. Events can also be
  observed at the Session level via Session Events.

Playgrounds add an interactive layer on top of Definitions, allowing workflows to be tested and debugged
visually from the BlobHub web application.

## Scheduler Primitives

Scheduler Blobs hold collections of **Schedules** that trigger workflow Executions on a time-based cadence.

```mermaid theme={null}
flowchart LR
    SCHED[/"Schedule"/]
    SCHED -->|type| ONE["one_time"]
    SCHED -->|type| CRON["recurring_cron"]
    SCHED -->|fires| EX1["Execution · 1"]
    SCHED -->|fires| EX2["Execution · 2"]
    SCHED -->|fires| EXN["Execution · N"]
```

* Schedules are either **one-time** (fire once at a specific instant) or **recurring cron** (fire repeatedly
  based on a cron expression).
* Every Schedule carries an IANA timezone and optional start/end date windows.
* Each Schedule retains a history of past firings and their outcomes.

## Operations

Any long-running action in BlobHub — such as committing a large Revision or uploading a model — is exposed
as an **Operation**. Operations can be polled for status and completion, and are how the platform models
asynchronous work consistently across all Blob Types.

## Putting It All Together

```mermaid theme={null}
flowchart TB
    ORG["Organization"]
    ORG --> WB[/"Workflow Blob"/]
    ORG --> SB[/"Scheduler Blob"/]
    ORG --> OB[/"ONNX Blob"/]

    WB --> WR["Revisions<br/>(Draft → Commit → Snapshot)"]
    WR --> DEF["Workflow Definition"]
    DEF --> SESS["Sessions"]
    SESS --> EXEC["Executions"]
    EXEC --> EVT["Events"]

    SB --> SR["Revisions"]
    SR --> SCHED["Schedules"]
    SCHED -->|trigger| EXEC

    OB --> OR["Revisions"]
    OR --> MODEL["ONNX Model"]

    classDef blob fill:#0D9373,stroke:#07C983,stroke-width:1px,color:#ffffff;
    class WB,SB,OB blob;
```

With these primitives — **Organization → Blob → Revision**, plus the Workflow, Scheduler, and ONNX engines
on top — the rest of the BlobHub documentation should feel like a natural extension of what you already know.