# cloudflare/orange architecture

> Architecture diagram of the GitHub repository cloudflare/orange, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudflare/orange
- Repository: https://github.com/cloudflare/orange

## Overview

##### Project Type and Purpose
- Orange Meets is a full-stack WebRTC demo application built with React/Remix, deployed on Cloudflare Workers.
- It’s designed to showcase Cloudflare Calls (WebRTC), optional TURN services, end-to-end encryption via Rust/WASM (MLS), and optional AI participant integration using OpenAI’s Realtime API.

##### File Structure Analysis
- **app/**
- React/Remix source code: entry.client.tsx & entry.server.tsx for hydration/SSR
- components/ (UI widget library), hooks/ (state & media logic), routes/ (Remix routing), durableObjects/ (stateful Cloudflare Durable Objects), utils/ (helpers, logging, Cloudflare Calls setup), mocks/ (Mock Service Worker for dev), styles/ (Tailwind)
- **public/**
- Static assets: wasm bundles for E2EE (rust-mls-worker), noise suppression workers, SW for mocks
- **rust-mls-worker/**
- Rust code (lib.rs, mls_ops.rs) compiled via build.sh into a WASM package for client-side MLS encryption
- **Configuration & Infra**
- server.ts: Cloudflare Worker entry that wires Remix, Durable Objects, D1 (Drizzle)
- drizzle.config.ts, migrations/: D1 database schema via Drizzle ORM
- wrangler*.toml: deployment settings per environment
- queue.ts: Durable Object Queue implementation for background tasks
- **Tests & Tooling**
- e2e-tests/ with Playwright, Vitest for unit tests, linters & formatters, GitHub Actions workflows

##### README Insights
- Confirms architecture uses Cloudflare Calls, Durable Objects for room state, optional TURN service, and optional OpenAI Realtime API for AI invites.

##### Main Components & Their Interactions
A. Client (Browser)
- UI: React components (app/components/) render video, audio controls, chat, AI invite, bug reporting.
- Hooks (app/hooks/) manage media devices, peer connections (Cloudflare Calls SDK), WebRTC stats, E2EE orchestration via Rust-WASM.
- WASM Modules:
– rust-mls-worker (MLS encryption)
– noise suppression worklet (public/noise)
- Mock Service Worker (public/mockServiceWorker.js) in dev.
B. Cloudflare Edge (server.ts)
- Remix request handler (SSR + API routes under app/routes/api.*)
- Durable Objects:
– ChatRoom.server.ts for per-room signaling, participant lists, chat history
– Queue durable object (queue.ts) for deferred tasks (e.g. analytics, logs)
- D1 Database (via Drizzle) for persistent metadata (e.g. user sessions, logs)
- Utilities: openai.server.ts for AI invites, getIceServers.server.ts for TURN credentials
C. Cloudflare Calls Service
- Signaling & TURN/STUN infrastructure powering WebRTC media streams
- Controlled via CALLS_APP_ID / CALLS_APP_SECRET
D. External Services
- Optional Cloudflare TURN Service (TURN_SERVICE_ID/TOKEN)
- Optional OpenAI Realtime API (OPENAI_MODEL_ENDPOINT / OPENAI_API_TOKEN)
E. CI/CD & Deployment
- Wrangler (wrangler.toml family) deploys Worker + Durable Objects + D1 migrations
- GitHub Actions runs lint, security scans (semgrep), tests

##### Architectural Patterns & Design Principles
- **Serverless Microservices**: Durable Objects for stateful room logic; queue DO for background jobs
- **SSR + CSR Hybrid**: Remix provides SEO-friendly SSR; React hydrates for rich client interactivity
- **Modular UI**: Small, reusable React components + hooks enforce separation of concerns
- **E2EE Pipeline**: Rust-WASM for cryptographic operations, integrated into client hooks
- **Infrastructure as Code**: Wrangler TOML defines environment-specific variables & secrets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser (Client)" 
        style BrowserLayer fill:#CCE5FF,stroke:#000
        BrowserUI["React Components"]:::frontend
        ReactHooks["React Hooks"]:::frontend
        EntryClient["entry.client.tsx"]:::frontend
        EntryServer["entry.server.tsx"]:::frontend
        MockSW["Mock Service Worker"]:::frontend
        MlsWasm["MLS E2EE WASM Module"]:::wasm
        Noise["Noise Suppression Worklet"]:::wasm
    end

    %% Edge Worker Layer
    subgraph "Cloudflare Edge Worker" 
        style EdgeLayer fill:#CCFFCC,stroke:#000
        Server["server.ts (Remix Worker)"]:::backend
        Routes["Remix Routes (SSR & API)"]:::backend
    end

    %% Durable Objects
    subgraph "Durable Objects" 
        style DOs fill:#CCFFCC,stroke:#000
        ChatRoomDO["ChatRoom Durable Object"]:::backend
        QueueDO["Queue Durable Object"]:::backend
    end

    %% Database
    subgraph "Persistent Storage"
        style DBLayer fill:#FFF0B3,stroke:#000
        D1DB["D1 Database (Drizzle)"]:::data
    end

    %% External Services
    subgraph "External Services"
        style ExtLayer fill:#E0E0E0,stroke:#000
        CallsService["Cloudflare Calls Service"]:::external
        TURNService["TURN Service"]:::external
        OpenAIService["OpenAI Realtime API"]:::external
    end

    %% Utilities
    subgraph "Edge Utilities"
        style UtilsLayer fill:#CCFFCC,stroke:#000
        TurnUtil["getIceServers.utility"]:::backend
        OpenAIUtil["openai.server.ts"]:::backend
        CallsUtil["callsTypes.ts"]:::backend
        Logging["logging & helpers"]:::backend
    end

    %% CI/CD & Infra
    subgraph "CI/CD & Deployment"
        style InfraLayer fill:#E0E0E0,stroke:#000
        CICD["GitHub Actions Workflows"]:::external
        WranglerCfg["wrangler.toml configs"]:::external
    end

    %% Connections
    BrowserUI -->|"uses"| ReactHooks
    EntryClient --> BrowserUI
    EntryServer --> BrowserUI
    BrowserUI -->|"HTTPS/WS"| Server
    Server -->|"SSR request"| EntryServer
    Server -->|"API request"| Routes
    Routes -->|"invoke"| ChatRoomDO
    Routes -->|"invoke"| TurnUtil
    Routes -->|"invoke"| OpenAIUtil
    Server -->|"persist metadata"| D1DB
    Server -->|"enqueue logs"| QueueDO
    ReactHooks -->|"load WASM"| MlsWasm
    ReactHooks -->|"load worklet"| Noise
    ReactHooks -->|"Cloudflare Calls SDK"| CallsService
    CallsService -->|"media streams"| BrowserUI
    BrowserUI -->|"WebRTC media"| CallsService
    BrowserUI -->|"encrypted frames"| MlsWasm
    Server -->|"analytics/events"| QueueDO
    Server -->|"logs/errors"| Logging
    TurnUtil -->|"provides ICE servers"| BrowserUI
    OpenAIUtil -->|"AI invites"| OpenAIService
    D1DB -->|"migrations"| WranglerCfg
    CICD -->|"deploy"| WranglerCfg

    %% Click Events
    click BrowserUI "https://github.com/cloudflare/orange/tree/main/app/components/"
    click ReactHooks "https://github.com/cloudflare/orange/tree/main/app/hooks/"
    click Routes "https://github.com/cloudflare/orange/tree/main/app/routes/"
    click EntryClient "https://github.com/cloudflare/orange/blob/main/app/entry.client.tsx"
    click EntryServer "https://github.com/cloudflare/orange/blob/main/app/entry.server.tsx"
    click MockSW "https://github.com/cloudflare/orange/blob/main/public/mockServiceWorker.js"
    click MlsWasm "https://github.com/cloudflare/orange/tree/main/public/e2ee/wasm-pkg/"
    click Noise "https://github.com/cloudflare/orange/blob/main/public/noise/noise-suppressor-worklet.esm.js"
    click Server "https://github.com/cloudflare/orange/blob/main/server.ts"
    click ChatRoomDO "https://github.com/cloudflare/orange/blob/main/app/durableObjects/ChatRoom.server.ts"
    click QueueDO "https://github.com/cloudflare/orange/blob/main/app/queue.ts"
    click D1DB "https://github.com/cloudflare/orange/blob/main/drizzle.config.ts"
    click TurnUtil "https://github.com/cloudflare/orange/blob/main/app/utils/getIceServers.server.ts"
    click OpenAIUtil "https://github.com/cloudflare/orange/blob/main/app/utils/openai.server.ts"
    click CallsUtil "https://github.com/cloudflare/orange/blob/main/app/utils/callsTypes.ts"
    click Logging "https://github.com/cloudflare/orange/blob/main/app/utils/logging.ts"
    click CICD "https://github.com/cloudflare/orange/blob/main/.github/workflows/check.yml"
    click WranglerCfg "https://github.com/cloudflare/orange/blob/main/wrangler.toml"

    %% Styles
    classDef frontend fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef backend fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef data fill:#FFF0B3,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef wasm fill:#E5CCFF,stroke:#333,stroke-width:1px
```
