Cloud Integration

This page describes how OpenGPEX connects to GPEX-Cloud for authentication, file storage, and synchronization.

Architecture

┌──────────────────────┐         ┌─────────────────────────────┐
│   OpenGPEX Editor     │         │       GPEX-Cloud              │
│                       │         │                              │
│  CloudServiceProtocol │ ◄─────► │  Auth API (Supabase)         │
│       │               │  HTTPS  │  Storage API (R2 presigned)  │
│       ▼               │         │  User API (profile, quota)   │
│  Cloud Menu UI        │         │                              │
└──────────────────────┘         └─────────────────────────────┘

CloudServiceProtocol

The editor communicates with the cloud via a protocol interface:

interface CloudServiceProtocol {
  // Authentication
  login(): Promise<AuthResult>;
  logout(): Promise<void>;
  getSession(): Promise<Session | null>;
  refreshToken(): Promise<string>;

  // File operations
  listFiles(params: ListParams): Promise<PaginatedFiles>;
  uploadFile(blob: Blob, meta: FileMeta): Promise<FileRecord>;
  downloadFile(fileId: string): Promise<Blob>;
  deleteFile(fileId: string): Promise<void>;

  // User
  getProfile(): Promise<UserProfile>;
  getQuota(): Promise<QuotaInfo>;
}

This protocol is injected into the editor at runtime — the editor core has zero direct dependencies on Supabase, Cloudflare, or any specific cloud vendor.

Authentication Flow

User clicks "Sign In"
    │
    ▼
Editor calls cloudService.login()
    │
    ▼
Redirect to OAuth provider (Google)
    │
    ▼
Callback → Supabase issues JWT
    │
    ▼
Token stored in httpOnly cookie
    │
    ▼
Editor receives session → updates Cloud Menu UI

File Storage (R2 Presigned Upload)

Files are stored on Cloudflare R2 using presigned URLs:

1. Editor requests upload URL from GPEX-Cloud API
2. API generates presigned PUT URL (valid 15 min)
3. Editor uploads .gpex blob directly to R2 (no proxy needed)
4. API records file metadata in PostgreSQL

This approach:

• Avoids body-size limits on the API server
• Enables direct client→R2 upload for maximum speed
• Keeps the API server stateless

Offline Resilience

When the user loses connectivity:

• The editor continues functioning fully (local IndexedDB persistence)
• Cloud operations are queued in memory
• On reconnection, queued operations are replayed
• Conflict resolution: last-write-wins with timestamp comparison

Token Management

Quota System

Quota is enforced server-side. The editor displays current usage in the Cloud Menu.

Next Steps

• Cloud Storage — User-facing guide for cloud features
• Architecture Overview — System-level context
• Plugin Security — Cloud mode restrictions

Last updated: 2026-06-14