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

> Explore the open-sse directory in OmniRoute, your guide to the SSE streaming engine. Understand its architecture and find comprehensive documentation for handlers, translators, and executors.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: architecture
- Published: 2026-07-02

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/routing/AUTO-COMBO.md).

### Utility and Type Definitions

Low-level infrastructure resides in `open-sse/utils/`, including [`proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/proxyFetch.ts) for egress handling, [`error.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/error.ts) for sanitization, and [`publicCreds.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/publicCreds.ts) for credential management. Central type definitions in [`open-sse/types.d.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/PROVIDER_REFERENCE.md)** lists the registry, executors, and translators as canonical sources for provider-specific behavior
- **[`docs/security/ERROR_SANITIZATION.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/ERROR_SANITIZATION.md)** points to [`open-sse/utils/error.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/error.ts) as the source of truth for error handling
- **[`docs/security/PUBLIC_CREDS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/PUBLIC_CREDS.md)** references [`open-sse/utils/publicCreds.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/publicCreds.ts) for credential policies
- **[`docs/security/EGRESS_POLICY.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/EGRESS_POLICY.md)** documents [`open-sse/utils/proxyDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyDispatcher.ts) for proxy configuration
- **[`docs/routing/AUTO-COMBO.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) for validation
2. [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) for dispatch
3. [`open-sse/translator/request/openai-to-openai.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/request/openai-to-openai.ts) for no-op translation
4. [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) for upstream communication

### Cross-Provider Translation (OpenAI to Claude)

To use Claude through the OpenAI-compatible interface:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/request/openai-to-claude.ts) for request transformation
- [`open-sse/executors/anthropic.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/anthropic.ts) for provider-specific execution
- [`open-sse/translator/response/claude-to-openai.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)** – Central dispatcher for all request types
- **[`open-sse/translator/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/index.ts)** – Entry point for translation logic
- **[`open-sse/translator/request/openai-to-claude.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/request/openai-to-claude.ts)** – Example request mapper
- **[`open-sse/translator/response/claude-to-openai.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/translator/response/claude-to-openai.ts)** – Example response mapper
- **[`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts)** – Default HTTP client for OpenAI-compatible providers
- **[`open-sse/executors/anthropic.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/anthropic.ts)** – Specialized executor for Claude
- **[`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)** – Multi-provider routing logic
- **[`open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFetch.ts)** – Egress and proxy handling
- **[`open-sse/types.d.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse.md) file. Instead, documentation is distributed across inline comments in source files like [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/default.ts) and specialized providers using dedicated files like [`anthropic.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/anthropic.ts).

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

The [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.