# MotorSignal — Phase 2D: Firebase Storage → Cloudflare R2 Migration & Architecture

**Document Version**: 1.0.0  
**Phase**: Phase 2D — Cloud Storage Migration & Cloud Sync Hardening  
**Status**: ARCHITECTURAL SPECIFICATION & MIGRATION GUIDE  

---

## 1. Executive Summary & Authoritative Principles

MotorSignal has migrated its large-object binary storage backend from **Firebase Cloud Storage** to **Cloudflare R2**, while preserving all existing offline-first guarantees, authentication models, and database contracts.

* **Drift SQLite Schema 5 remains authoritative for all raw telemetry and local ride recordings.**
* **Firebase Authentication remains authoritative for rider identity (`uid`).**
* **Cloud Firestore remains the structured cloud database for queryable metadata, summaries, and performance runs.**
* **Cloudflare R2 is the high-capacity, low-cost object/blob storage layer for compressed forensic bundles (`telemetry.zip`).**
* **Cloud synchronization is completely downstream of local persistence.**

---

## 2. Previous vs. New Architecture

```
PREVIOUS ARCHITECTURE (Phase 2B/2C):
Local SQLite (Schema 5) ──► SyncManager ──► FirebaseSyncProvider
                                                ├── Cloud Firestore (Metadata)
                                                └── Firebase Cloud Storage (telemetry.zip)

NEW ARCHITECTURE (Phase 2D):
Local SQLite (Schema 5) ──► SyncManager ──► FirebaseSyncProvider
                                                ├── Cloud Firestore (Metadata & R2 Object Key)
                                                └── Cloudflare Worker Gateway
                                                        └── Cloudflare R2 (telemetry.zip)
```

---

## 3. Cloudflare Worker Gateway Architecture

### Project Location
```
cloudflare/motorsignal-r2-worker/
├── src/
│   └── index.ts        # TypeScript Worker logic with Firebase JWT verification
├── wrangler.toml       # R2 bucket bindings & environment configuration
├── package.json        # Dependencies & scripts
└── README.md           # Deployment and testing instructions
```

### Server-Side Path Derivation & Zero-Trust Boundary
The Flutter client **NEVER** communicates with Cloudflare R2 using permanent access keys or secrets (`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`).

Instead, the client sends its Firebase ID token to the Cloudflare Worker. The Worker:
1. Validates the Firebase JWT cryptographic signature, expiration (`exp`), and project audience (`aud`).
2. Extracts the verified `sub` claim (`authenticatedUid`).
3. Validates the `X-Remote-Ride-Id` header against a strict regex (`/^[a-zA-Z0-9_-]{3,100}$/`).
4. Derives the canonical R2 object key server-side:
   ```
   users/{authenticatedUid}/rides/{validatedRemoteRideId}/telemetry.zip
   ```
5. Streams the binary payload directly into the Cloudflare `R2Bucket` binding.

---

## 4. Endpoints & API Contract

### Binary Upload Endpoint
* **Method**: `PUT`
* **Path**: `/r2/upload`
* **Headers**:
  * `Authorization`: `Bearer <FirebaseIdToken>`
  * `Content-Type`: `application/zip`
  * `X-Remote-Ride-Id`: `ride_<localRideId>_<timestamp>`
  * `X-Bundle-Sha256`: `<sha256-hash>`
  * `X-App-Version`: `<semantic-version>`
* **Body**: Raw binary bytes of `telemetry.zip`.
* **Response**:
  ```json
  {
    "success": true,
    "objectKey": "users/<uid>/rides/<remoteRideId>/telemetry.zip",
    "size": 348120,
    "etag": "\"8f4b2c1...\"",
    "uploadedAt": "2026-08-31T12:00:00.000Z"
  }
  ```

### Telemetry Download Endpoint
* **Method**: `GET`
* **Path**: `/r2/download?rideId=<remoteRideId>`
* **Headers**:
  * `Authorization`: `Bearer <FirebaseIdToken>`
* **Response**: Streamed binary `telemetry.zip` attachment.

---

## 5. Firestore Document Model

Firestore documents continue to reside at `/users/{uid}/rides/{remoteRideId}` with queryable metadata, referencing Cloudflare R2:

```json
{
  "localRideId": 14,
  "remoteRideId": "ride_14_20260831_080000",
  "uid": "aB3kL99zX...",
  "startTime": "2026-08-31T08:00:00.000Z",
  "endTime": "2026-08-31T08:45:12.000Z",
  "distanceMiles": 24.8,
  "topSpeedMph": 74.2,
  "maxLeanLeft": 32.1,
  "maxLeanRight": 35.4,
  "maxAccelG": 0.58,
  "maxBrakingG": -0.88,
  "averageSpeed": 41.5,
  "movingTime": 2160,
  "stoppedTime": 552,
  "qualityScore": 98,
  "qualityRating": "EXCELLENT",
  "telemetryBundle": {
    "provider": "cloudflare-r2",
    "objectKey": "users/aB3kL99zX.../rides/ride_14_20260831_080000/telemetry.zip",
    "status": "uploaded",
    "bundleSizeBytes": 348120,
    "sha256": "8f4b2c1..."
  },
  "telemetryBundlePath": "users/aB3kL99zX.../rides/ride_14_20260831_080000/telemetry.zip",
  "bundleSizeBytes": 348120,
  "syncVersion": 2,
  "uploadedAt": "2026-08-31T08:46:00.000Z"
}
```

---

## 6. Security Model & Secrets Management

1. **Flutter App**: Contains **zero** Cloudflare credentials, API keys, or R2 tokens.
2. **Cloudflare Worker**: Managed via Cloudflare dashboard or Wrangler secrets (`wrangler secret put FIREBASE_PROJECT_ID`).
3. **Firestore Security Rules**: Unchanged (`users/{userId}/rides/{rideId}` allows read/write only if `request.auth.uid == userId`).
4. **Git Safety**: Secrets, `.env`, and private JSON files remain strictly excluded via `.gitignore`.

---

## 7. Migration & Backward Compatibility

* **Existing Local Rides**: All local SQLite rides remain authoritative and fully accessible.
* **Existing Firestore Records**: Legacy documents containing Firebase Storage references remain readable. New uploads write `syncVersion: 2` and `provider: "cloudflare-r2"`.
* **Outbox Continuity**: The persistent local `SyncOutbox` continues tracking items by `${localRideId}_${providerId}`.

---

## 8. Failure & Retry Behavior

| Failure Mode | Worker Status | Client Sync State | Recovery Strategy |
| :--- | :--- | :--- | :--- |
| **Worker 5xx / Timeout** | 500 / 503 | `RETRY_WAIT` | Exponential backoff ($5\text{s} \rightarrow 30\text{m}$) |
| **Invalid / Expired Token** | 401 / 403 | `AUTH_REQUIRED` | Awaits token refresh / user login |
| **Malformed Ride ID** | 400 | `FAILED` | Terminal validation error |
| **Network Unavailable** | Client error | `WAITING_FOR_NETWORK` | Resumes automatically when online |
| **R2 Success, Firestore Drop** | 200 OK | `RETRY_WAIT` | Re-attempts Firestore commit; R2 upload is idempotent |

---

## 9. Future Camera & Video Compatibility

When video/camera features are introduced in Phase 3:
* Video segments ($100\text{ MB} - 4\text{ GB}$) will be streamed to R2 under `users/{uid}/rides/{remoteRideId}/video/chunk_01.mp4`.
* The Worker gateway can issue multipart chunk upload authorization URLs directly to Cloudflare R2 without routing massive video payloads through Firestore or mobile memory buffers.