Skip to content

integration-flow.md

Latest commit

 

History

History
421 lines (344 loc) · 13.8 KB

integration-flow.md

File metadata and controls

421 lines (344 loc) · 13.8 KB

Orbito Integration Flow

Overview

This document provides step-by-step flows and sequence diagrams for key Orbito operations.

Flow 1: Website Onboarding

Steps

  1. Developer visits Orbito Platform Dashboard

    • Goes to the Orbito admin portal

  2. Register New Website

    • Fills form: domain, website name, owner email
    • Clicks "Register Website"

  3. Backend Generates API Key

    • Creates UUID for website_id
    • Generates unique api_key
    • Stores in websites collection

  4. Developer Receives API Key

    • Dashboard displays API key
    • Developer copies key for SDK installation

Sequence Diagram

Developer          Dashboard          Backend             MongoDB
   |                   |                  |                   |
   |--Register Form--->|                  |                   |
   |                   |--POST /register->|                   |
   |                   |                  |--Insert website-->|
   |                   |                  |<--Success---------||
   |                   |<--API Key--------|                   |
   |<--Display Key-----|                  |                   |
   |                   |                  |                   |

Flow 2: SDK Installation & Initialization

Steps

  1. Developer Installs SDK

    npm install orbito-react-sdk

  2. Developer Wraps App with OrbitoProvider

    <OrbitoProvider apiKey="orbito_key_..." domain="shop.example.com">
  <App />
</OrbitoProvider>

  3. SDK Initializes on Page Load

    • Creates WebSocket/message listener
    • Initializes local action registry
    • Sends ORBITO_SDK_READY message to window

  4. Developer Wraps UI Components

    const { register } = useOrbitoAction({
  actionId: 'add-to-cart',
  intent: 'addToCart',
  description: 'Add product to cart',
  // ...
});

<button {...register(() => handleAddToCart())}>
  Add to Cart
</button>

  5. SDK Registers Actions with Backend

    • On component mount, SDK calls POST /api/v1/actions/register
    • Backend stores action in MongoDB

Sequence Diagram

Page Load      SDK           Backend        MongoDB
   |            |               |              |
   |--Mount---->|               |              |
   |            |--Initialize-->|              |
   |            |               |              |
   |            |<--Ready-------|              |
   |<--Ready----|               |              |
   |            |               |              |
[Component Mount]               |              |
   |            |               |              |
   |--Mount---->|               |              |
   |            |--Register---->|              |
   |            |   Action      |--Upsert----->|
   |            |               |<--Success----|
   |            |<--Success-----|              |
   |            |               |              |

Flow 3: Extension Discovers Actions

Steps

  1. User Opens Orbito-enabled Website

    • Website loads with SDK initialized

  2. Extension Content Script Detects SDK

    • Listens for ORBITO_SDK_READY message
    • Sends message to extension popup

  3. User Opens Extension Popup

    • Popup UI displays "Orbito Enabled" badge
    • Shows loading state

  4. Extension Fetches Actions from Backend

    • Extracts domain from current tab URL
    • Calls GET /api/v1/actions?domain=shop.example.com

  5. Backend Returns Available Actions

    • Queries MongoDB for active actions
    • Returns action list with metadata

  6. Extension Displays Actions in UI

    • Lists actions with descriptions
    • Groups by intent or page
    • Shows action parameters

Sequence Diagram

User      Extension(Popup)  Content Script    SDK         Backend      MongoDB
 |              |                 |              |             |            |
 |--Open Tab--->|                 |              |             |            |
 |              |                 |              |             |            |
 |              |                 |<--SDK Ready--|             |            |
 |              |<--SDK Detected--|              |             |            |
 |              |                 |              |             |            |
 |--Click Ext-->|                 |              |             |            |
 |              |                 |              |             |            |
 |              |--Get domain---->|              |             |            |
 |              |                 |              |             |            |
 |              |----------GET /actions?domain=...------------>|            |
 |              |                 |              |             |--Query---->|
 |              |                 |              |             |<--Actions--|
 |              |<-------------------Action List---------------|            |
 |              |                 |              |             |            |
 |<--Display----|                 |              |             |            |
 |   Actions    |                 |              |             |            |
 |              |                 |              |             |            |

Flow 4: User Executes Action via Extension

Steps

  1. User Selects Action in Extension

    • Types natural language: "add 2 items to cart"
    • OR clicks action from list

  2. Extension Parses Intent & Parameters

    • Matches prompt to action intent
    • Extracts parameters (quantity: 2)

  3. Extension Highlights Target Element (Optional)

    • Sends ORBITO_HIGHLIGHT_ACTION to content script
    • Content script forwards to SDK
    • SDK adds visual highlight to element

  4. Extension Sends Execution Request

    • Content script sends ORBITO_EXECUTE_ACTION message
    • Includes action_id and parameters

  5. SDK Executes Action

    • Looks up action in local registry
    • Validates parameters
    • Calls registered callback function
    • Triggers actual UI interaction

  6. SDK Returns Result

    • Sends ORBITO_ACTION_RESULT message
    • Includes success status and return data

  7. Extension Displays Feedback

    • Shows success notification
    • Removes highlight
    • Updates usage analytics

  8. SDK Reports Usage to Backend

    • Calls POST /api/v1/actions/{action_id}/usage
    • Backend increments usage_count in MongoDB

Sequence Diagram

User   Extension   Content    SDK        Page/App     Backend    MongoDB
 |        |         Script     |             |           |          |
 |--Type--|         |          |             |           |          |
 | "add"--->        |          |             |           |          |
 |        |         |          |             |           |          |
 |        |--Match--|          |             |           |          |
 |        | Intent  |          |             |           |          |
 |        |         |          |             |           |          |
 |        |------HIGHLIGHT---->|             |           |          |
 |        |         |--------->|             |           |          |
 |        |         |          |--Highlight->|           |          |
 |        |         |          |  Element    |           |          |
 |        |         |          |             |           |          |
 |        |------EXECUTE------>|             |           |          |
 |        |         |  ACTION  |             |           |          |
 |        |         |--------->|             |           |          |
 |        |         |          |--Validate-->|           |          |
 |        |         |          | Params      |           |          |
 |        |         |          |             |           |          |
 |        |         |          |--Execute--->|           |          |
 |        |         |          | Callback    |           |          |
 |        |         |          |             |           |          |
 |        |         |          |             |--Update-->|          |
 |        |         |          |             |  State    |          |
 |        |         |          |             |           |          |
 |        |         |          |<--Result----|           |          |
 |        |         |          |             |           |          |
 |        |         |          |----POST /usage-------->|          |
 |        |         |          |             |           |--Inc---->|
 |        |         |          |             |           | Count    |
 |        |         |          |             |           |<---------||
 |        |         |          |             |           |          |
 |        |         |<--RESULT-|             |           |          |
 |        |<-----------|       |             |           |          |
 |        | Success    |       |             |           |          |
 |        |            |       |             |           |          |
 |<--Show-|            |       |             |           |          |
 | Success|            |       |             |           |          |
 |        |            |       |             |           |          |

Flow 5: Admin Manages Actions (Dashboard)

Steps

  1. Admin Logs into Dashboard

    • Authenticates with owner credentials

  2. Dashboard Displays Registered Websites

    • Lists all websites with action counts

  3. Admin Selects Website

    • Clicks on domain to view details

  4. Dashboard Shows Website Actions

    • Fetches GET /api/v1/actions?domain=...
    • Displays table with:
      • Action ID
      • Intent
      • Description
      • Usage count
      • Status (active/inactive)

  5. Admin Toggles Action Status

    • Clicks toggle switch
    • Dashboard sends PATCH /api/v1/actions/{action_id}/status
    • Backend updates is_active field

  6. Extension Respects Active Status

    • Only active actions appear in extension
    • Inactive actions are filtered out by backend

Sequence Diagram

Admin    Dashboard     Backend      MongoDB
  |          |            |            |
  |--Login-->|            |            |
  |          |            |            |
  |          |--GET Websites---------->|
  |          |            |<--List-----|
  |<--Show---|            |            |
  | Websites |            |            |
  |          |            |            |
  |--Select->|            |            |
  | Website  |            |            |
  |          |--GET Actions---------->||
  |          |            |<--List-----|
  |<--Show---|            |            |
  | Actions  |            |            |
  |          |            |            |
  |--Toggle->|            |            |
  | Status   |            |            |
  |          |--PATCH Status--------->|
  |          |            |--Update--->|
  |          |            |<--Success--|
  |          |<--Success--|            |
  |<--Updated|            |            |
  |          |            |            |

Flow 6: Dynamic Action Registration (SPA Navigation)

Steps

  1. User Navigates to New Page in SPA

    • React Router changes route

  2. New Components Mount

    • Components with useOrbitoAction initialize

  3. SDK Detects New Actions

    • Adds to local registry
    • Registers with backend (debounced)

  4. Previous Page Components Unmount

    • SDK removes from local registry
    • Backend actions remain (marked as inactive or kept)

  5. Extension Updates Available Actions

    • Optionally polls backend for updated list
    • Or SDK sends ORBITO_ACTION_STATE_CHANGED message

Sequence Diagram

User    SPA/Router   Component    SDK        Backend
 |          |            |           |            |
 |--Click-->|            |           |            |
 | Link     |            |           |            |
 |          |--Navigate->|           |            |
 |          |            |           |            |
 |          |            |--Mount--->|            |
 |          |            |           |            |
 |          |            |           |--Register->|
 |          |            |           |  Action    |
 |          |            |           |<--Success--|
 |          |            |           |            |
 |          |<--Unmount--|           |            |
 |          | (Old Comp) |           |            |
 |          |            |---------->|            |
 |          |            | Unregister|            |
 |          |            |  (local)  |            |
 |          |            |           |            |

Error Handling Flows

Scenario 1: Action Execution Fails

Extension    SDK        Backend
    |          |            |
    |--Execute-|            |
    |  Action  |            |
    |          |--Validate->|
    |          |  Params    |
    |          |            |
    |          |<--Invalid--|
    |          | Parameter  |
    |          |            |
    |<--Error--|            |
    | Result   |            |
    |          |            |
[Show Error Notification]  |

Scenario 2: SDK Not Detected

Extension    Content     Page
    |         Script      |
    |--Check-->|          |
    | SDK      |          |
    |          |--Listen->|
    |          | 5s       |
    |          |          |
    |<--Timeout|          |
    |          |          |
[Show "SDK Not Detected"]|

Scenario 3: Backend Unavailable

SDK       Backend
  |          |
  |--Register
  |  Action  |
  |          X (503)
  |          |
  |--Retry-->|
  | (3x)     |
  |          X
  |          |
[Queue locally, retry later]
  |          |
  |--Retry-->|
  | (1 min)  |
  |          |
  |<--Success|

Summary

These flows ensure:

  1. Decoupled development: Each team can work independently using contracts
  2. Reliable communication: Message protocol handles all edge cases
  3. Data consistency: Backend serves as single source of truth
  4. User experience: Visual feedback and error handling throughout
  5. Scalability: Async operations and debouncing prevent overload