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

# How BlobRouter works

> Cloud optimization starting with storage — audits, migrations, and smart routing.

<Info>
  **BlobRouter v0.1** · Last updated: August 2026 · Architecture version: **2.0**
</Info>

BlobRouter is a **cloud optimization platform** whose first capability is storage cost optimization. Storage is the entry point because access patterns are measurable, trust required is low, and savings show up quickly.

It is not “just a storage SDK.” The SDK is one way to keep optimizing after the free audit.

## Two entry points

### 1. Free — AWS S3 cost audit

Connect a **read-only** IAM role → BlobRouter scans your buckets → you see waste and recommendations. Nothing changes until you approve it.

### 2. Paid — Migration + smart router

Approve migrations (never automatic) → cold objects move to cheaper storage, hot objects toward R2 → new uploads via the SDK go to the cheapest suitable provider.

## Two credential models

Never confuse these:

| Model           | Used for                       | What we store                          | Trust                                               |
| --------------- | ------------------------------ | -------------------------------------- | --------------------------------------------------- |
| **A — Scanner** | Free audit                     | Role ARN + External ID only            | Low — temporary STS credentials, expire in \~1 hour |
| **B — Router**  | Presigned upload/download URLs | Access keys encrypted with AES-256-GCM | Medium — write access scoped to your buckets        |

Scanner credentials are **never** long-lived AWS access keys. Router credentials are decrypted only in Worker memory when generating presigned URLs.

## Product flow

```
Free audit
  → Connect read-only IAM role
  → Scan S3 (about 2–5 minutes)
  → See monthly waste + ranked recommendations

Optional paid migration
  → Review recommendations
  → Approve explicitly
  → Migrate cold → B2, hot → R2

Optional smart router
  → Connect provider credentials
  → Install SDK
  → New uploads routed by cost + priority
```

## Invariants

* **No byte proxying** — files go client → provider via presigned URLs
* **Client-owned storage** — we never host object bytes
* **Scanner is read-only** — zero write permissions on the audit role
* **No auto-remediation** — migrations require explicit approval
* **Deterministic routing in v1** — cost formula + priority rules, not ML

## Architecture sketch

```
Developer / Dashboard
        │
        ▼
   BlobRouter API
   (Cloudflare Workers)
        │
   ┌────┴────┐
   ▼         ▼
 Scanner   Router
 (STS)   (presigned URLs)
   │         │
   ▼         ▼
  Your AWS   Your S3 / R2 / B2
```

See [Architecture](/architecture) for upload, scan, and migration flows in detail.