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

# Architecture

> How the Adaptive Data Fabric presents every backend as one logical bucket — placement, caching, and access over S3 and MCP.

OneBucket sits between your clients and your storage backends. Clients speak **S3** or **MCP** to a single endpoint; OneBucket resolves each request to wherever the data actually lives — cloud, on-prem, or edge — and moves or caches data according to policy.

## The Adaptive Data Fabric

The fabric is the core abstraction: **location-independent access to unstructured data**. It has three jobs:

* **Connect natively** — native S3 and MCP interfaces reach every cloud, on-prem, and edge source, with no application changes.
* **Place by policy** — policy-driven placement and adaptive movement keep data in the right place at the right time.
* **Access anywhere** — intelligent caching and replication make distributed data feel local.

Your applications see **one logical bucket namespace**. Behind it, objects may live in AWS S3, Azure Blob, Google Cloud Storage, Wasabi, Akave, on-prem, edge, or air-gapped stores — and may move between them without the client noticing.

## Access interfaces

Each OneBucket deployment is per cluster, and its endpoints live on your cluster host:

| Interface   | Endpoint                          | Speaks                                                                                            |
| ----------- | --------------------------------- | ------------------------------------------------------------------------------------------------- |
| S3 gateway  | `s3.<cluster>.onebucket.io`       | Full S3 API with AWS SigV4 auth — buckets, objects, multipart uploads, versioning, presigned URLs |
| Storage MCP | `mcp-core.<cluster>.onebucket.io` | MCP tools to browse, read, and manage objects ([Claude connector](/connectors/claude))            |
| Events MCP  | `synapse.<cluster>.onebucket.io`  | MCP tools to list, get, and tail storage events                                                   |

Both MCP endpoints authenticate via the OneBucket authorization server ("axon") using standard OAuth 2.1 with PKCE; the S3 gateway uses your access key / secret key pair. See [How authentication works](/connectors/claude#how-authentication-works).

## Placement and movement

Objects are placed and moved by policy rather than by hand:

* **Policy-driven placement** decides which backend holds an object when it is written.
* **Adaptive movement** relocates data as access patterns and policies change.
* **Explicit operations** — `copy`, `move`, and `migrate` — let you relocate objects across backends on demand. These run asynchronously: they return once queued, so a destination may not be readable immediately.
* **`locate`** reports which configured backends currently hold an object.

## Caching and replication

To cut egress cost and latency, OneBucket serves repeat reads locally:

* **Edge caching** keeps hot objects close to where they are read.
* **Prefetch** warms the cache ahead of demand (`prefetch` via MCP, or as part of policy).
* **Replication** keeps copies in multiple backends where policy requires it.

## Governance and audit

Access control is enforced once, at the fabric — one policy layer across every backend. Every operation is scoped to your organization and access key; cross-organization access is not possible. Detailed **storage events** stream from the events endpoint, so you can audit activity with `list_events`, `get_event`, and `tail_events`, filterable by time, bucket, and action.

## Next steps

<CardGroup cols={2}>
  <Card title="S3 API compatibility" icon="code" href="/reference/s3-api">
    What the S3 gateway supports and how to authenticate.
  </Card>

  <Card title="Connect Claude" icon="plug" href="/connectors/claude">
    Give AI native access to the fabric over MCP.
  </Card>
</CardGroup>