API Architecture

ryOS APIs are implemented as Node-style route handlers under api/, served by the standalone Bun API server, with shared apiHandler and api/_utils primitives providing consistent CORS, method routing, auth, and error handling patterns.

Architecture Overview

graph TB
    subgraph Client["Client Layer"]
        UI[React UI]
        Hooks[Custom Hooks]
    end
    
    subgraph API["API Runtime (standalone Bun server)"]
        Handler[apiHandler + api/_utils]
        ChatAPI[chat]
        SongAPI[songs]
        SpeechAPI[speech]
        RoomsAPI[rooms]
        MessagesAPI[rooms/messages]
        ListenAPI[listen/sessions]
        PresenceAPI[presence]
        UsersAPI[users]
        IEAPI[ie-generate]
        AppletAPI[applet-ai]
    end
    
    subgraph AI["AI Providers"]
        OpenAI[OpenAI]
        Anthropic[Anthropic]
        Google[Google]
    end
    
    subgraph Storage["Storage"]
        Redis[(Redis
Upstash REST / Standard)]
        ObjectStorage[(Object Storage
S3 compatible)]
    end
    
    subgraph Realtime["Real-time"]
        RealtimeProvider[Pusher / Local WS]
    end
    
    UI --> Hooks
    Hooks --> API
    Handler --> ChatAPI
    Handler --> SongAPI
    Handler --> RoomsAPI
    Handler --> ListenAPI
    API --> AI
    API --> Storage
    API --> Realtime
    RoomsAPI --> RealtimeProvider

API Directory Structure

api/
├── _utils/                    # Shared API primitives
│   ├── api-handler.ts         # Shared handler wrapper (CORS, methods, auth, errors)
│   ├── request-auth.ts        # Header parsing + auth resolution
│   ├── redis.ts               # Redis client factory (Upstash REST + standard Redis/ioredis)
│   ├── storage.ts             # Object storage adapter (S3 compatible)
│   ├── realtime.ts            # Realtime event abstraction (Pusher + local WebSocket)
│   ├── runtime-config.ts      # Client runtime config (origins, realtime, pusher)
│   ├── _cors.ts               # CORS helpers (incl. wildcard subdomain patterns)
│   ├── _ssrf.ts               # SSRF-safe fetch/URL validation
│   ├── _rate-limit.ts         # Rate limiting primitives
│   ├── _validation.ts         # Input validation helpers
│   ├── _logging.ts            # Structured request logging
│   ├── _analytics.ts          # Lightweight per-day API usage analytics
│   ├── _sse.ts                # SSE helpers
│   ├── _memory.ts             # AI conversation memory helpers
│   ├── _song-service.ts       # Song storage service
│   ├── _hash.ts               # Hashing utilities
│   ├── _url.ts                # URL utilities
│   ├── og-share.ts            # OpenGraph share image generation
│   ├── auth/                  # Token/password/auth helpers
│   ├── contacts.ts            # Contacts sync helpers
│   ├── heartbeats.ts          # Heartbeat scheduling helpers
│   ├── ryo-conversation.ts    # Unified conversation preparation (web + Telegram)
│   ├── _cookie.ts             # Auth cookie helpers
│   ├── telegram-format.ts     # Telegram message formatting
│   ├── song-library-state.ts  # Song library state helpers
│   └── telegram*.ts           # Telegram bot integration helpers
├── airdrop/                   # AirDrop file sharing endpoints
├── auth/                      # Auth endpoints
├── rooms/                     # Chat room endpoints
├── listen/                    # Listen-together session endpoints
├── songs/                     # Song library endpoints
├── messages/                  # Bulk message endpoints
├── presence/                  # Presence switching + heartbeat endpoints
├── users/                     # User search endpoints
├── ai/                        # AI helper endpoints
├── chat/                      # Chat endpoint with tool definitions
├── sync/                      # Cloud sync endpoints (backup + logical sync domains)
├── telegram/                  # Telegram bot link/disconnect endpoints
├── cron/                      # Scheduled tasks (telegram heartbeat)
├── webhooks/                  # Webhook handlers (telegram)
└── [endpoint].ts              # Individual top-level endpoints (chat, speech, ie-generate, etc.)

Middleware Utilities

The API layer standardizes route behavior through apiHandler plus shared api/_utils/* modules. This keeps CORS handling, method routing, auth resolution, and error handling consistent across refactored endpoints. CORS supports wildcard subdomain patterns (e.g. *.example.com) via API_ALLOWED_ORIGINS.

Imports

Routes import directly from the focused api/_utils/* modules (there is no barrel re-export module):

import { apiHandler } from "../_utils/api-handler.js";
import { createRedis } from "../_utils/redis.js";
import { getEffectiveOrigin, isAllowedOrigin, setCorsHeaders } from "../_utils/_cors.js";
import { extractAuth, extractAuthNormalized } from "../_utils/auth/index.js";

Domain-specific constants (Redis key prefixes, TTLs) live in their owning module, e.g. api/rooms/_helpers/_constants.ts and api/_utils/auth/_constants.ts.

apiHandler Pattern

Refactored routes use apiHandler() as the entry wrapper:

export default apiHandler<RequestBody>(
  {
    methods: ["POST"],
    auth: "required",
    bodySchema: RequestBodySchema, // Zod schema (implies parseJsonBody)
  },
  async ({ res, user, body, logger, startTime }) => {
    logger.info("Request accepted", { username: user?.username });
    logger.response(200, Date.now() - startTime);
    res.status(200).json({ success: true });
  }
);

• Shared CORS + origin checks

• Method allow-list enforcement (405 on unsupported methods)
• Optional/required auth resolution via request-auth.ts
• Optional bodySchema request-body validation: any object with a safeParse(data) method works, and a Zod schema (z.object(...)) satisfies it directly. The parsed/typed body is exposed as body; invalid bodies short-circuit with 400 { error: "validation_error", issues }. Setting bodySchema implies parseJsonBody.
• Shared Redis/logger/request context for handlers
• Consistent 500 handling for uncaught exceptions

Specialized route wrappers

Routes should default to apiHandler(). If an endpoint needs multipart upload, webhook verification, or cron-only auth behavior, it should use a specialized wrapper that keeps the same shared entry flow instead of introducing a separate request-context pattern.

Auth Utilities

> See Also: API Design Guide for comprehensive patterns and examples.

API Endpoint Inventory

Authentication APIs

Core APIs

Media APIs

AI Generation APIs

Communication APIs

Listen APIs

| /api/listen/sessions/[id]/transfer-host | POST | Transfer session host | | /api/listen/sessions/[id]/assign-dj | POST | Assign the session DJ | | /api/listen/sessions/[id]/remote-command | POST | Submit remote playback command |

IRC APIs

Apple Services APIs

Analytics & TV APIs

Cloud Sync APIs

Telegram APIs

Utility APIs

AirDrop APIs

Frontend API Client Layer

Client-side API access is centralized in src/api/:

• src/api/core.ts - shared request wrapper, auth headers, error normalization

• src/api/auth.ts - login/register/token verification/logout flows
• src/api/rooms.ts - room, message, and presence operations
• src/api/admin.ts - admin actions and dashboard operations (incl. analytics)
• src/api/songs.ts - song CRUD/import operations
• src/api/listen.ts - listen-together session flows
• src/api/telegram.ts - Telegram bot linking and status operations
• src/api/irc.ts - IRC server registry operations

AI Provider Abstraction

Model IDs and metadata are defined in src/shared/aiModels.ts. Server provider wiring is in api/_utils/_aiModels.ts.

Supported Models (AI SDK 6.0)

The API uses Vercel AI SDK 6.0 with structured outputs for type-safe responses.

Model Selection

// api/_utils/_aiModels.ts
export const getModelInstance = (model: SupportedModel): LanguageModel => {
  switch (model) {
    case "gpt-5.5":
      return openai("gpt-5.5");
    case "sonnet-4.6":
      return anthropic("claude-sonnet-4-6");
    case "gemini-3-flash":
      return google("gemini-3-flash-preview");
    case "gemini-3.1-pro-preview":
      return google("gemini-3.1-pro-preview");
  }
};

Chat API

Streaming Architecture

sequenceDiagram
    participant Client
    participant API as /api/chat
    participant AI as AI Provider
    participant Tools as Tool Handlers
    
    Client->>API: POST (messages, model)
    API->>AI: ToolLoopAgent.stream()
    
    loop Stream Response
        AI-->>API: Token/Tool Call
        
        alt Tool Call
            API->>Tools: Execute tool
            Tools-->>API: Tool result
            API->>AI: Continue with result
        else Text Token
            API-->>Client: SSE chunk
        end
    end
    
    API-->>Client: Stream complete

Tool Calling System

The chat API provides tools for system control:

tools: {
  launchApp: {
    description: "Launch ryOS application",
    parameters: z.object({
      appId: z.enum(["finder", "textedit", "ipod", ...]),
      initialData: z.unknown().optional(),
    }),
  },
  
  mediaControl: {
    description: "Control music/karaoke/videos/TV playback",
    parameters: z.object({
      target: z.enum(["music", "karaoke", "videos", "tv"]).optional(),
      action: z.enum(["toggle", "play", "pause", "next", "previous", ...]),
      title: z.string().optional(),
      artist: z.string().optional(),
    }),
  },
  
  generateHtml: {
    description: "Generate HTML applet",
    parameters: z.object({
      title: z.string(),
      icon: z.string(),
      code: z.string(),
    }),
  },
  
  // ... more tools
}

System Prompts

// api/_utils/_aiPrompts.ts
export const CORE_PRIORITY_INSTRUCTIONS = `
  You are Ryo, an AI assistant in ryOS...
`;

export const RYO_PERSONA_INSTRUCTIONS = `
  Ryo's personality and background...
`;

export const CODE_GENERATION_INSTRUCTIONS = `
  HTML applet generation rules...
`;

export const TOOL_USAGE_INSTRUCTIONS = `
  VFS and tool usage patterns...
`;

Song API

Split Storage Architecture

flowchart TB
    subgraph "Request"
        REQ[API Request]
    end
    
    subgraph "Redis Storage"
        META[(media:song:{id}:meta
Lightweight)]
        CONTENT[(media:song:{id}:content
Heavy Data)]
        SET[(media:song:ids
ID Set)]
    end
    
    REQ --> |List/Search| META
    REQ --> |Full Song| META
    META --> |UUID Lookup| CONTENT
    REQ --> |All IDs| SET

Endpoints

Speech APIs

Text-to-Speech

// api/speech.ts
const providers = {
  openai: {
    models: ["tts-1", "tts-1-hd"],
    voices: ["alloy", "echo", "fable", "onyx", "nova", "shimmer"],
  },
  elevenlabs: {
    models: ["eleven_multilingual_v2", "eleven_turbo_v2"],
    voices: ["custom voice IDs"],
  },
};

// Dual provider support
if (model === "elevenlabs") {
  return generateElevenLabsSpeech(text, voiceId, modelId);
} else {
  return generateSpeech({
    model: openai.speech("tts-1"),
    text,
    voice,
  });
}

Audio Transcription

// api/audio-transcribe.ts
const transcription = await openai.audio.transcriptions.create({
  file: audioFile,
  model: "whisper-1",
});

Rate Limiting

Counter-Based Limiting

// api/_utils/_rate-limit.ts
export async function checkCounterLimit({
  key,
  windowSeconds,
  limit,
}: CounterLimitArgs): Promise<CounterLimitResult> {
  // Atomic increment
  const newCount = await redis.incr(key);
  
  // Set expiry on first request
  if (newCount === 1) {
    await redis.expire(key, windowSeconds);
  }
  
  const ttl = await redis.ttl(key);
  
  if (newCount > limit) {
    return { 
      allowed: false, 
      count: newCount, 
      remaining: 0,
      resetSeconds: ttl,
    };
  }
  
  return { 
    allowed: true, 
    remaining: limit - newCount,
  };
}

Rate Limit Configurations

Authentication

Token Validation

// api/_utils/auth/_validate.ts
export async function validateAuth(
  redis: RedisLike,
  username: string,
  authToken: string,
  options: { allowExpired?: boolean; refreshOnGrace?: boolean } = {}
): Promise<AuthValidationResult> {
  // 1. Check active token
  const userKey = getUserTokenKey(username, authToken);
  const exists = await redis.exists(userKey);
  
  if (exists) {
    // Refresh TTL on use
    await redis.expire(userKey, USER_TTL_SECONDS);
    return { valid: true, expired: false };
  }
  
  // 2. Check grace period for expired tokens
  if (options.allowExpired) {
    const lastTokenKey = getLastTokenKey(username);
    const lastTokenData = await redis.get(lastTokenKey);
    // ... grace period logic
  }
  
  return { valid: false };
}

Auth Headers

Token Configuration

CORS Handling

// api/_utils/_cors.ts
export function isAllowedOrigin(origin: string | null): boolean {
  if (!origin) return false;
  
  // Always allow Tailscale origins
  if (isTailscaleOrigin(origin)) return true;
  
  const env = getRuntimeEnv();
  const configuredOrigins = getConfiguredAllowedOrigins();

  // Explicit self-host allowlist (API_ALLOWED_ORIGINS) takes precedence.
  // Supports wildcard subdomain patterns like "*.example.com".
  if (configuredOrigins.allowAll) return true;
  if (configuredOrigins.origins.has(normalizedOrigin)) return true;
  if (configuredOrigins.subdomainSuffixes.some(s => hostname.endsWith(s))) return true;
  
  // Fallback to environment-based checks
  if (env === "production") return origin === PROD_ALLOWED_ORIGIN;
  return isLocalhostOrigin(origin);
}

Response Patterns

Handlers use apiHandler() plus res.status().json() / res.status().end(). Rate-limit responses are built inline in route handlers using _rate-limit.ts primitives. Error bodies typically follow { error, code?, details? }.

All error responses follow a consistent format:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "details": { "field": "value" }
}

Rate limit errors include additional fields:

{
  "error": "rate_limit_exceeded",
  "limit": 30,
  "retryAfter": 45,
  "scope": "burst"
}

SSE Streaming Response

const stream = new ReadableStream({
  async start(controller) {
    for await (const chunk of aiStream) {
      controller.enqueue(`data: ${JSON.stringify(chunk)}\n\n`);
    }
    controller.enqueue("data: [DONE]\n\n");
    controller.close();
  },
});

return new Response(stream, {
  headers: {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    "Connection": "keep-alive",
  },
});

Runtime Configuration

• The standalone Bun server (scripts/api-standalone-server.ts) discovers and executes the api/* handlers via a request/response adapter.

• API development/runtime scripts use Bun (bun run dev:api, bun run api:start).

Realtime Provider Modes

Realtime delivery is selected at runtime:

Cloud Sync v2 publishes sync-ops events on per-user sync channels; small remote changes can be applied directly from the realtime payload without an extra HTTP fetch.

Redis Key Patterns

Related Documentation

• API Design Guide - Implementation patterns and best practices

• Chat API - Detailed chat API documentation
• Song API - Song API reference
• AI Generation APIs - IE and Applet AI
• Rooms API - Chat room management
• Messages API - Chat messaging
• Utility APIs - Link preview, iframe check, share applet