Orbito - AI-Native Web Platform

🚀 Overview

Orbito is an SDK-first platform that makes any website controllable by AI agents. Instead of fragile web scraping, Orbito allows developers to explicitly expose UI functionalities ("intents") through a React SDK, creating a reliable bridge between human-designed interfaces and AI agents.

---

🎯 Problem Statement

Current AI agents struggle with websites because:

• ❌ Websites are designed for humans, not AI
• ❌ Scraping is fragile and breaks with UI changes
• ❌ No standardized way for agents to interact with web UIs
• ❌ No permission/access control for agent actions

Orbito solves this by allowing developers to wrap UI components and declare agent-accessible actions with explicit schemas.

---

🏛️ Architecture

Orbito consists of three main components:

┌───────────────────────────────────────┐
│         Orbito Ecosystem                  │
└───────────────────────────────────────┘
           │                  │
    ┌──────┴────────────────┴──────┐
    │           │                │      │
┌───┴───┐   ┌───┴────┐      ┌────┴─────┐
│ React │   │ Backend │      │ Browser  │
│  SDK  │   │Platform│      │Extension│
└────────┘   └─────────┘      └──────────┘

1. React SDK (packages/react-sdk/)

• npm package: orbito-react-sdk
• Developers install it in their React apps
• Provides <OrbitoProvider> and useOrbitoAction() hook
• Wraps UI components to expose actions
• Registers actions with Backend Platform
• Handles execution requests from Browser Extension

2. Backend Platform (packages/backend-platform/)

• FastAPI server + MongoDB database
• Central action registry for all Orbito-enabled websites
• Provides discovery API for extensions/agents
• Admin dashboard for managing actions
• Handles authentication via API keys

3. Browser Extension (packages/browser-extension/)

• Chrome extension (Manifest V3)
• Discovers actions available on current page
• Accepts natural language prompts from users
• Multi-step workflow execution - Breaks down complex tasks into sequential actions
• Navigation handling - Automatically waits for page navigation and React Router changes
• Executes actions via message passing to SDK
• Provides visual feedback and step-by-step execution results

---

📝 How It Works

For Website Developers (Supply Side)

1. Install SDK:

   npm install orbito-react-sdk

2. Wrap your app:

   import { OrbitoProvider } from 'orbito-react-sdk';
   
   <OrbitoProvider apiKey="orbito_key_xxx" domain="mysite.com">
     <App />
   </OrbitoProvider>

3. Expose actions:

   import { useOrbitoAction } from 'orbito-react-sdk';
   
   const { register } = useOrbitoAction({
     actionId: 'add-to-cart',
     intent: 'addToCart',
     description: 'Adds product to shopping cart',
     parameters: {
       quantity: { type: 'number', required: false, default: 1 }
     },
     onExecute: handleAddToCart
   });
   
   <button {...register()}>Add to Cart</button>

For End Users (Demand Side)

1. Install Orbito Extension (Chrome Web Store)
2. Visit Orbito-enabled website
3. Click extension icon to see available actions
4. Type natural language:
   • Single action: "add 2 items to cart"
   • Multi-step workflow: "Add product 1 to cart, go to cart, proceed to checkout, fill name with John Doe, fill email with john@example.com, and complete payment"
5. Actions execute automatically with proper sequencing and navigation handling

---

📁 Project Structure

orbito/
├── packages/
│   ├── react-sdk/              # React SDK package
│   │   ├── src/
│   │   │   ├── OrbitoProvider.tsx
│   │   │   ├── useOrbitoAction.ts
│   │   │   ├── OrbitoRegistry.ts
│   │   │   └── OrbitoClient.ts
│   │   └── demo/              # Demo React app
│   │
│   ├── backend-platform/       # Backend + Dashboard
│   │   ├── backend/           # FastAPI server
│   │   │   ├── server.py
│   │   │   ├── models/
│   │   │   ├── routes/
│   │   │   └── database.py
│   │   └── frontend/          # Admin dashboard (React)
│   │
│   └── browser-extension/      # Chrome extension
│       ├── manifest.json
│       ├── src/
│       │   ├── popup/         # Extension popup UI
│       │   ├── content/       # Content script
│       │   └── background/    # Service worker
│       └── public/
│
└── docs/                      # Integration contracts & guides
    ├── api-contract.md        # Backend API specification
    ├── message-protocol.md    # Extension ↔ SDK communication
    ├── data-models.md         # Database schemas
    ├── integration-flow.md    # Sequence diagrams
    ├── puneet-react-sdk.md    # React SDK developer guide
    ├── shreyas-backend.md     # Backend developer guide
    └── chayan-browser-extension.md  # Extension developer guide

---

🛠️ Tech Stack

React SDK

• Language: TypeScript
• Framework: React 18+
• Build: Rollup/Webpack
• Package Manager: npm/yarn

Backend Platform

• Language: Python 3.11+
• Framework: FastAPI
• Database: MongoDB (motor driver)
• Auth: API Keys
• Deployment: Docker + Kubernetes (future)

Browser Extension

• Language: TypeScript
• UI: React
• Manifest: V3
• Build: Webpack
• Browser: Chrome (Firefox support later)

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• Python 3.11+
• MongoDB (local or Atlas)
• Chrome browser (for extension development)

Quick Start

1. Clone repository:

git clone <repo-url>
cd orbito

2. Setup Backend:

cd packages/backend-platform/backend
pip install -r requirements.txt
# Start MongoDB locally
mongod --dbpath ./data
# Run server
uvicorn server:app --reload --port 8001

3. Setup React SDK:

cd packages/react-sdk
npm install
npm run build
# Run demo
cd demo
npm install
npm run dev

4. Setup Browser Extension:

cd packages/browser-extension
npm install
npm run build
# Load in Chrome: chrome://extensions > Load unpacked > select dist/

---

📚 Documentation

All technical documentation is in the /docs folder:

• API Contract: Complete REST API specification
• Message Protocol: Extension ↔ SDK communication
• Data Models: Database schemas and validation
• Integration Flow: Sequence diagrams for key operations
• Multi-Step Workflows: Guide to multi-step action chaining and workflow execution

Developer Guides

• React SDK Guide: For Puneet (SDK development)
• Backend Guide: For Shreyas (Backend development)
• Extension Guide: For Chayan (Extension development)

Demo Applications

• Demo1 Actions Guide: Complete guide to all actions in the demo e-commerce app
• Demo1 README: Setup and usage instructions for the demo app

---

🤝 Contributing

Git Workflow

Each developer works in their designated package folder:

• Puneet (React SDK): /packages/react-sdk/
• Shreyas (Backend): /packages/backend-platform/backend/
• Chayan (Extension): /packages/browser-extension/

Commit Prefixes:

• SDK commits: [sdk] Your commit message
• Backend commits: [backend] Your commit message
• Extension commits: [extension] Your commit message
• Docs commits: [docs] Your commit message

Branch Strategy:

• Main branch: main
• Feature branches: feature/<component>-<feature-name>
• Example: feature/sdk-action-highlight, feature/backend-rate-limiting

---

✅ Testing Strategy

Unit Tests

• SDK: Jest + React Testing Library
• Backend: pytest
• Extension: Jest

Integration Tests

1. SDK → Backend: Test action registration
2. Extension → Backend: Test action discovery
3. Extension → SDK: Test action execution via messages

E2E Tests

• Playwright for full workflow testing
• Test: User types prompt → Action executes → UI updates

---

📌 Roadmap

MVP (Current Phase)

• ✅ Monorepo structure
• ✅ Integration contracts
• 🚧 React SDK core
• 🚧 Backend API
• 🚧 Browser Extension
• ☐ End-to-end integration testing

Phase 2

• ✅ Multi-step action chaining and workflow execution
• ✅ Navigation detection and waiting for React Router
• ✅ Dynamic actions (single action for multiple elements)
• ☐ Admin dashboard (website/action management)
• ☐ Advanced NLP for prompt parsing
• ☐ Visual action highlighting
• ☐ Analytics and usage tracking

Phase 3

• ☐ Framework-agnostic core (Vue, Angular support)
• ☐ Server-side action execution
• ☐ AI agent API (for programmatic access)
• ☐ Marketplace for Orbito-enabled sites

---

💬 Contact & Support

• Team Lead: [Your Name]
• Slack Channel: #orbito-dev
• Documentation: /docs
• Issues: GitHub Issues

---

📜 License

MIT License - See LICENSE file for details

---

Built with ❤️ by the Orbito Team