# RTIE — Full developer documentation for LLMs

## What is RTIE?

RTIE (Real Time Intelligence Engine) is a multi-tenant, AI-native realtime runtime for building realtime products.
It is the infrastructure beneath RTIE Labs products such as vAuction, vArcade, DesiWasi,
and Playdemy. Third-party developers can build their own products on RTIE Core.

RTIE is modular: every feature is a "module" that tenants enable. Modules declare routes, events,
SDK surface, and private-preview MCP tools. The platform provides identity, realtime state, billing, and webhooks.

Canonical API host: https://api.rtie.ai
Product frontends call api.rtie.ai and send X-RTIE-Product-Key when product context is required.

---

## Authentication

Credential surfaces:
- RTIE API key: `rtie_live_*` or `rtie_test_*` — passed as `X-API-Key: <key>` or `Authorization: Bearer <key>`
- Hosted auth JWT — Supabase Auth for RTIE Cloud and first-party products
- BYOA/OIDC adapter — Auth0, Firebase, Cognito, custom OIDC, or guest identity mapped to an RTIE actor
- RTIE module/session token — short-lived token from `/v1/runtime/connect`

Get API keys at: https://cloud.rtie.ai → API Keys

All requests are tenant-scoped. An API key can never read another tenant's data. Third-party runtime users do not need Supabase Auth; verify your provider token server-side and mint a scoped RTIE session token.

---

## MCP private preview

RTIE is building a public MCP server at https://mcp.rtie.ai. Public tool calling is private preview
until T20 ships. The configuration shape below is for tenants with preview access.

### Claude Code (.mcp.json)
```json
{
  "mcpServers": {
    "rtie": {
      "type": "http",
      "url": "https://mcp.rtie.ai/mcp",
      "headers": { "Authorization": "Bearer ${RTIE_API_KEY}" }
    }
  }
}
```

### Cursor (.cursor/mcp.json)
```json
{
  "mcpServers": {
    "rtie": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/client-http", "https://mcp.rtie.ai/mcp"],
      "env": { "RTIE_API_KEY": "rtie_live_..." }
    }
  }
}
```

MCP manifest target: https://mcp.rtie.ai/.well-known/mcp/manifest.json

---

## Core modules and planned MCP tools

### rooms (universal)
Session containers for all realtime interactions.

Routes: GET /v1/rooms, POST /v1/rooms, GET /v1/rooms/{id}, POST /v1/rooms/{id}/activate, POST /v1/rooms/{id}/close

Planned MCP tools:
- list_rooms — List rooms for the tenant (filter by status: idle|active|closed)
- create_room — Create a room (name, slug required)
- get_room — Get room details (roomId required)
- activate_room — Open a room for participants
- close_room — Close a room and end the session
- add_room_member — Add a member with optional role (host|co-host|participant|viewer)

### presence (universal)
Live participant tracking within rooms.

Routes: GET /v1/rooms/{roomId}/presence

Planned MCP tools:
- get_presence — List users currently in a room (roomId required)

### chat (universal)
Realtime in-session messaging.

Routes: GET /v1/rooms/{roomId}/messages, POST /v1/rooms/{roomId}/messages

Planned MCP tools:
- send_chat_message — Send a message to a room (roomId, body required)
- list_chat_messages — List recent messages in a room (roomId required, limit optional)

### auctions (product-bundle — requires operator workspace)
Live auction state, bids, timers. Powers vAuction.

Routes: GET/POST /v1/auctions, POST /v1/auctions/{id}/start, POST /v1/auctions/{id}/close

Planned MCP tools:
- create_auction — Create a live auction (title required, roomId optional)
- start_auction — Open bidding (auctionId required)
- close_auction — Close and resolve winner (auctionId required) [destructive]
- get_winning_bid — Get current high bid (auctionId required)

Agentic Commerce planned MCP tools (product-bundle):
- listing_browse — Browse all active listings (mode: fixed|timed_auction|live_auction, limit)
- listing_get — Get listing details (listing_id required)
- auction_list_live — List live auctions with real-time prices
- auction_get_high_bid — Get current high bid on a listing (listing_id required)
- auction_place_bid — Place a bid [REQUIRES HUMAN CONFIRMATION] (listing_id, amount_cents required)
- listing_buy_now — Buy-now checkout, returns checkout URL [REQUIRES HUMAN CONFIRMATION]

### payments (universal)
Stripe-powered orders and payouts.

Routes: GET /v1/payments/orders, GET /v1/payments/orders/{id}

Planned MCP tools:
- get_payment_status — Check payment status for an order (orderId required)
- list_orders — List orders (status filter: pending|processing|paid|failed|refunded)

### webhooks (universal)
HMAC-signed event delivery via Cloudflare Queues.

Routes: GET/POST /v1/webhooks, GET /v1/webhooks/{id}/deliveries

Planned MCP tools:
- list_webhook_endpoints — List registered endpoints
- create_webhook_endpoint — Register a new endpoint (url, secret required; eventTypes optional)
- list_webhook_deliveries — List delivery attempts for an endpoint (endpointId required)

### actions (universal — Action Engine)
Signal → rules → real-time actions (<350ms end-to-end).

Routes: POST /v1/actions/signals, GET /v1/actions/rules, POST /v1/actions/rules, GET /v1/actions/log

Planned MCP tools:
- ingest_signal — Submit a signal for rule evaluation (signal_type, source, payload required)
- get_action_log — Query the decision log (limit optional)
- get_rules — Get tenant rules
- set_rules — Replace all tenant rules [destructive] (rules array required)

### sync (universal)
Multiplayer game state engine (CF Durable Objects + SpacetimeDB).

Routes: GET/POST /v1/sync/games, POST /v1/sync/games/{id}/rooms, GET/POST /v1/sync/rooms/{id}/state

Planned MCP tools:
- sync_list_games — List game definitions
- sync_create_game — Register a new game (name required)
- sync_create_room — Create a game room (gameId required)
- sync_list_rooms — List active rooms for a game (gameId required)
- sync_get_state — Get current room state snapshot (roomId required)
- sync_push_state — Push a server-authoritative state update (roomId, state required)
- sync_broadcast_event — Broadcast event to all players (roomId, type required)

---

## Building a module

Install the module SDK:
```bash
bun add @rtie/module-sdk
```

```typescript
// my-module/index.ts
import { defineModule } from "@rtie/module-sdk";
import { Hono } from "hono";

const router = new Hono();
router.get("/v1/my-module/things", async (c) => {
  return c.json({ things: [] });
});

export default defineModule({
  manifest: {
    id: "my-module",
    name: "My Module",
    version: "1.0.0",
    publisher: "Acme Corp",
    tier: "marketplace",
    description: "Does something useful.",
    routes: [{ method: "GET", path: "/v1/my-module/things", description: "List things" }],
    events: ["my-module.thing.created"],
    sdk_surface: ["listThings"],
    mcp_tools: [
      {
        name: "list_things",
        description: "List things.",
        inputSchema: { type: "object", properties: {} },
        handler: { kind: "http", method: "GET", path: "/v1/my-module/things" },
        annotations: { readOnlyHint: true },
      },
    ],
    requires: ["auth"],
    conflicts: [],
    contexts: {
      supportedTypes: ["room"],
      policyActions: ["my-module.things.read"],
    },
  },
  routes: (app) => app.route("/", router),
});
```

---

## Schema / migrations

RTIE uses Drizzle ORM with Postgres on Supabase (via HyperDrive).

```bash
# Apply migrations
source ~/.zshrc && bun db:migrate

# Generate new migration from schema changes
bun db:generate
```

Schema: `packages/db/src/schema/`
Migrations: `drizzle/`

IMPORTANT: Do not use Supabase MCP/CLI to run migrations. Use `bun db:migrate`.

---

## Realtime (SpacetimeDB via RTIE)

Never connect to SpacetimeDB directly. Use @rtie/sdk subscriptions or declare
`manifest.spacetime` tables/reducers and let the provisioner compose them.

```typescript
// Correct — via @rtie/sdk
const sub = rtie.presence.watch(roomId, (state) => { /* react to changes */ });

// Wrong — never do this
import { DbConnection } from "@clockworklabs/spacetimedb-sdk"; // ❌
```

---

## Action Engine — signal → rules → actions

Signal types: any string (e.g. `churn_risk`, `bid_velocity`, `user_intent`)
Action types: `agent_trigger`, `ui_event`, `module_call`, `state_update`

```json
POST /v1/actions/signals
{
  "signal_type": "churn_risk",
  "source": "ml_model",
  "payload": { "score": 0.87, "userId": "usr_123" },
  "confidence": 0.87
}
```

Rule shape:
```json
{
  "name": "Retention offer on churn risk",
  "signalType": "churn_risk",
  "conditions": [{ "field": "confidence", "op": "gte", "value": 0.8 }],
  "actionType": "ui_event",
  "actionConfig": { "event": "show_retention_offer" },
  "priority": 10,
  "enabled": true
}
```

---

## Deploy

All RTIE workers deploy to Cloudflare Workers via wrangler:

```bash
source ~/.zshrc && bunx wrangler deploy
```

Do NOT deploy to Railway, Vercel, or AWS. RTIE is Cloudflare-native.

---

## Key rules when building on RTIE

1. **Never call Supabase directly** — use RTIE module APIs and @rtie/sdk
2. **Never call SpacetimeDB directly** — use manifest.spacetime + @rtie/sdk
3. **Never call Cloudflare APIs directly** — use RTIE module interfaces
4. **Every table needs context_id** — modules attach state to the Context Graph
5. **Modules communicate via events** — not direct cross-module SQL
6. **API keys are tenant-scoped** — you cannot read another tenant's data
7. **Migrations via bun db:migrate** — not Supabase CLI or MCP

---

## Resources

- Cloud: https://cloud.rtie.ai
- API: https://api.rtie.ai
- Docs: https://docs.rtie.ai
- MCP private preview: https://mcp.rtie.ai
- AI tools: https://docs.rtie.ai/ai-tools
- RTIE.md: https://rtie.ai/RTIE.md