Understanding the open-sse Directory in OmniRoute: Architecture and Documentation

The open-sse directory in OmniRoute serves as the core Server-Sent Events (SSE) streaming engine, converting HTTP requests into provider-agnostic streams through handlers, translators, and executors documented across source files and reference guides.

The open-sse workspace powers OmniRoute’s ability to route AI requests from a unified OpenAI-compatible API to heterogeneous upstream providers. While no single open-sse.md file exists, comprehensive documentation is distributed across inline code comments, architectural reference files, and the source of truth in modules like open-sse/handlers/chatCore.ts.

Architecture of the open-sse Streaming Engine

The open-sse directory implements a layered pipeline that processes every incoming request through validation, translation, execution, and response transformation.

Entry Points and Request Validation

Next.js API routes in src/app/api/v1/**/route.ts act as minimal wrappers that validate request bodies using Zod schemas and enforce API-key policies before handing off to the SSE core. For example, src/app/api/v1/chat/completions/route.ts validates incoming chat completion requests and delegates to the central handler.

Core Handler Layer

The open-sse/handlers/chatCore.ts file contains the handleChatCore() function—the central hub for every request type including chat, embeddings, images, and audio. This module performs signature caching, rate-limit checks, and delegates to either a single provider or the combo routing engine.

Translation Layer

The open-sse/translator/ directory contains bidirectional converters between provider APIs. Files like open-sse/translator/request/openai-to-claude.ts map OpenAI request shapes to Claude’s expected format, while open-sse/translator/response/claude-to-openai.ts converts Claude responses back to OpenAI-compatible SSE streams.

Execution Layer

Provider-specific HTTP clients reside in open-sse/executors/. Most providers reuse open-sse/executors/default.ts, while special cases like Cursor or Antigravity extend this base class. The DefaultExecutor handles TLS configuration, header construction via open-sse/utils/opencodeHeaders.ts, and upstream connection management.

Service Layer

Higher-level orchestration logic lives in open-sse/services/. The open-sse/services/combo.ts module implements the combo-routing engine that distributes requests across multiple providers, while open-sse/services/autoCombo/ contains the scoring algorithm documented in docs/routing/AUTO-COMBO.md.

Utility and Type Definitions

Low-level infrastructure resides in open-sse/utils/, including proxyFetch.ts for egress handling, error.ts for sanitization, and publicCreds.ts for credential management. Central type definitions in open-sse/types.d.ts standardize request/response shapes and SSE event structures across the workspace.

Where Documentation Lives in the open-sse Directory

Documentation for open-sse is decentralized across reference files that cite source code as the authoritative source:

• docs/reference/PROVIDER_REFERENCE.md lists the registry, executors, and translators as canonical sources for provider-specific behavior
• docs/security/ERROR_SANITIZATION.md points to open-sse/utils/error.ts as the source of truth for error handling
• docs/security/PUBLIC_CREDS.md references open-sse/utils/publicCreds.ts for credential policies
• docs/security/EGRESS_POLICY.md documents open-sse/utils/proxyDispatcher.ts for proxy configuration
• docs/routing/AUTO-COMBO.md explains the auto-combo scoring engine implemented in open-sse/services/autoCombo/

Practical Code Examples for open-sse

Basic Chat Completion Request

When you call the OmniRoute API, you invoke the open-sse pipeline:

import fetch from 'node-fetch';

const resp = await fetch('https://my-omniroute-host/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-my-key',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    messages: [{ role: 'user', content: 'Hello, world!' }],
    stream: true,
  }),
});

for await (const line of resp.body!.pipeThrough(new TextDecoderStream())) {
  if (line.startsWith('data:')) {
    console.log(JSON.parse(line.slice(5)));
  }
}

Under the hood, this flows through:

1. src/app/api/v1/chat/completions/route.ts for validation
2. open-sse/handlers/chatCore.ts for dispatch
3. open-sse/translator/request/openai-to-openai.ts for no-op translation
4. open-sse/executors/default.ts for upstream communication

Cross-Provider Translation (OpenAI to Claude)

To use Claude through the OpenAI-compatible interface:

await fetch('https://my-omniroute-host/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'anthropic/claude-3-sonnet-20240229',
    messages: [{ role: 'user', content: 'Summarize the article.' }],
    stream: true,
  }),
});

The open-sse directory handles this via:

• open-sse/translator/request/openai-to-claude.ts for request transformation
• open-sse/executors/anthropic.ts for provider-specific execution
• open-sse/translator/response/claude-to-openai.ts for response normalization

Direct Handler Invocation for Testing

You can bypass HTTP and test the open-sse core directly:

import { handleChatCore } from '../../open-sse/handlers/chatCore.ts';
import { Request } from 'node-fetch';

const mockReq = new Request('http://localhost', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'openai/gpt-4o-mini',
    messages: [{ role: 'user', content: 'What is the weather?' }],
    stream: false,
  }),
});

const resp = await handleChatCore(mockReq);
const json = await resp.json();
console.log(json);

This works because handleChatCore accepts a standard Request object and returns a Response, encapsulating the entire open-sse pipeline.

Key Files in the open-sse Directory

• open-sse/handlers/chatCore.ts – Central dispatcher for all request types
• open-sse/translator/index.ts – Entry point for translation logic
• open-sse/translator/request/openai-to-claude.ts – Example request mapper
• open-sse/translator/response/claude-to-openai.ts – Example response mapper
• open-sse/executors/default.ts – Default HTTP client for OpenAI-compatible providers
• open-sse/executors/anthropic.ts – Specialized executor for Claude
• open-sse/services/combo.ts – Multi-provider routing logic
• open-sse/utils/proxyFetch.ts – Egress and proxy handling
• open-sse/types.d.ts – Centralized TypeScript definitions

Summary

• The open-sse directory in OmniRoute implements a complete SSE streaming engine without a single centralized README, using source files as documentation
• open-sse/handlers/chatCore.ts serves as the primary entry point for request processing, handling caching, rate limiting, and provider selection
• The translation layer in open-sse/translator/ enables interoperability between OpenAI, Claude, Gemini, and other providers through bidirectional converters
• Reference documentation in docs/reference/ and docs/security/ explicitly cites open-sse source files as the source of truth for provider behavior and security policies
• You can interact with the open-sse layer either through standard HTTP API calls or by directly importing handleChatCore for programmatic testing

Frequently Asked Questions

Is there a dedicated README for the open-sse directory?

No, the OmniRoute repository does not contain a standalone open-sse.md file. Instead, documentation is distributed across inline comments in source files like open-sse/handlers/chatCore.ts and reference documents in docs/reference/ and docs/security/ that link directly to the implementation files as authoritative sources.

How does open-sse handle different AI providers?

The open-sse directory uses a translator pattern where open-sse/translator/request/ files convert incoming OpenAI-formatted requests to provider-specific formats, while open-sse/translator/response/ files map provider responses back to OpenAI-compatible SSE streams. Executors in open-sse/executors/ handle the actual HTTP transport, with most providers using default.ts and specialized providers using dedicated files like anthropic.ts.

What is the role of chatCore.ts in the open-sse directory?

The open-sse/handlers/chatCore.ts file exports handleChatCore(), the central dispatch function that every API route invokes. It performs request validation, signature caching, rate-limit checks, and delegates to either a single provider executor or the combo routing service. This module coordinates the entire request lifecycle from receipt through upstream dispatch.

How can I test the open-sse handlers locally?

You can import handleChatCore directly from open-sse/handlers/chatCore.ts and invoke it with a standard Request object, as shown in the code examples above. This bypasses the HTTP layer and Next.js routing, allowing you to test translation logic, executor selection, and error handling in isolated unit tests without starting a full server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}