### 🔄 Ring API Client Workflow

**Goal:**
This workflow describes how we authenticate the user with Ring, retrieve and convert their Ring camera stream, and deliver it to the mobile app via WebRTC.

#### 📶 Workflow

sequenceDiagram
    participant User as 👤 User
    participant App as 📱 Mobile App
    participant API as ☁️ Backend API
    participant DB as 💾 Database
    participant Hub as 🏠 Hub (Ring API Client)
    participant RingCloud as ☁️ Ring Cloud
    participant MediaMTX as 🎥 MediaMTX (Hub)
    participant Mobile as 📱 Mobile Viewer

    %% Step 1: User login
    User->>App: ① Enter Ring credentials (username, password, MFA)
    App->>API: ② Submit login request
    API->>RingCloud: ③ Authenticate and get token
    RingCloud-->>API: ④ Return access + refresh token
    API->>DB: ⑤ Store token securely

    %% Step 2: Get and add Ring camera
    App->>API: ⑥ Request list of Ring cameras
    API->>RingCloud: ⑦ Get list of cameras on account
    RingCloud-->>API: ⑧ Return camera metadata (device ID, name, etc.)
    API-->>App: ⑨ Send camera list to app
    User->>App: ⑩ Select Ring camera to add
    App->>API: ⑪ Call add Ring camera
    API->>DB: ⑫ Store selected camera info
    API->>Hub: ⑬ Sync access token + selected camera to Ring API Client

    %% Step 3: Start streaming from selected Ring camera
    Mobile->>API: ⑭ Request to start stream (with Ring camera ID)
    API->>Hub: ⑮ Call /start-stream with Ring device ID
    Hub->>RingCloud: ⑯ Start stream session for selected camera
    Hub->>MediaMTX: ⑰ Convert RTSP and publish stream
    MediaMTX-->>Mobile: ⑱ Stream video via WebRTC