Where Are the Core Request-Processing Handlers Located in OmniRoute?

OmniRoute's core request-processing handlers live in the open-sse/handlers package, with the central orchestration centered in open-sse/handlers/chatCore.ts and its specialized sub-modules.

The OmniRoute open-source repository (diegosouzapw/OmniRoute) implements a modular pipeline architecture for processing AI chat and completions requests. Understanding where these core request-processing handlers are located is essential for anyone extending the framework, debugging streaming issues, or implementing custom middleware. This guide maps every stage of the pipeline to its corresponding source file.

The Entry Point: API Routes Delegate to the Core

Every request begins in Next.js API route handlers under src/app/api/v1/. The chat completions endpoint serves as the primary gateway.

src/app/api/v1/chat/completions/route.ts receives the HTTP request and applies initial guards:

• CORS headers
• Request ID and correlation ID injection
• Prompt-injection detection
• Authentication validation

After these checks, control passes to handleChat, which imports from the core handler package. This separation keeps HTTP concerns distinct from business logic.

import { handleChat } from "@/sse/handlers/chat";
import { errorResponse } from "@omniroute/open-sse/utils/error";

export async function POST(req: Request) {
  try {
    // Guards applied here...
    const result = await handleChat(req);
    return result;
  } catch (err) {
    return errorResponse(err);
  }
}

The Central Orchestrator: chatCore.ts

open-sse/handlers/chatCore.ts is the heart of OmniRoute's request-processing pipeline. This module exports handleChatCore, which coordinates every downstream stage.

The function signature and opening operations reveal the pipeline's structure:

export async function handleChatCore(request: Request) {
  const body = await request.json();

  // Tool identity extraction
  const toolMap = extractRequestToolIdentityMap(body);

  // Memory and skill injection
  const withMemory = await injectMemoryAndSkills(body);

  // Build provider-specific request
  const setup = resolveChatCoreRequestSetup(withMemory);

  // Semantic cache check
  const cached = await checkSemanticCache(setup);
  if (cached) return cached;

  // Executor invocation, streaming, finalization...
}

Each call in this sequence delegates to a dedicated sub-module, making the core readable and testable.

Pipeline Stage Handlers: Specialized Sub-Modules

The open-sse/handlers/chatCore/ directory contains focused handlers for each processing stage. These are the core request-processing handlers responsible for specific transformations.

Request Setup and Validation

open-sse/handlers/chatCore/requestSetup.ts normalizes incoming payloads and constructs the internal request model. It applies provider-specific defaults—converting OpenAI-style parameters to Anthropic or Google formats when needed, for example.

Tool Identity Extraction

open-sse/handlers/chatCore/requestToolIdentity.ts maps external tool IDs from client requests to internal representations. This abstraction lets the executor layer work with normalized tool references regardless of how clients label them.

Memory and Skill Injection

open-sse/handlers/chatCore/memorySkillsInjection.ts augments requests with:

• Persistent conversation memory retrieved from storage
• On-the-fly skill function calls injected as system messages or tool definitions

This handler ensures context from previous turns accompanies each request to the provider.

Semantic Cache Layer

open-sse/handlers/chatCore/semanticCache.ts performs vector-similarity checks before expensive upstream calls. When a cached embedding matches within threshold, the handler returns the stored response immediately—bypassing provider round-trips entirely.

Model Lifecycle and Policy Enforcement

open-sse/handlers/chatCore/modelLifecyclePolicy.ts enforces operational constraints:

• Per-model cooldown periods
• Quota consumption tracking
• Model lockout rules for deprecated or experimental endpoints

Streaming Response Handlers

The open-sse/handlers/chatCore/stream*.ts files manage Server-Sent Events (SSE) delivery. Key modules include:

• streamingPipeline.ts — assembles the SSE stream and manages backpressure
• streamFinalize.ts — computes token usage, injects final metadata, and closes connections cleanly

These handlers also inject keep-alive frames to prevent gateway timeouts during slow provider responses.

Error Sanitization

open-sse/utils/error.ts supports the core handlers by transforming raw exceptions into safe response payloads. Stack traces are stripped, and error codes map to consistent HTTP status codes per the project's security policies.

Summary

OmniRoute's core request-processing handlers follow a clear organizational pattern:

• Entry delegation — API routes in src/app/api/v1/*/route.ts forward to core handlers
• Central orchestration — open-sse/handlers/chatCore.ts coordinates the full pipeline
• Stage-specific handlers — sub-modules under open-sse/handlers/chatCore/ handle validation, memory, caching, policy, and streaming
• Cross-cutting utilities — open-sse/utils/error.ts ensures consistent error handling

This architecture lets developers instrument, replace, or extend any stage without disturbing adjacent components.

Frequently Asked Questions

What file should I edit to add custom request validation?

Modify open-sse/handlers/chatCore/requestSetup.ts. This handler receives the raw client payload and is the appropriate place to inject custom field validation or default value logic before the request model is finalized.

How does OmniRoute handle streaming timeouts?

The streaming handlers under open-sse/handlers/chatCore/stream*.ts inject periodic keep-alive SSE comments. streamingPipeline.ts monitors provider activity and can trigger circuit-breaker logic if chunks stall beyond configured thresholds.

Can I disable the semantic cache for specific requests?

Yes. The checkSemanticCache function in open-sse/handlers/chatCore/semanticCache.ts respects a cache: false flag in the request body. When present, the handler skips cache lookup and proceeds directly to upstream invocation.

Where are rate limits enforced in the pipeline?

Rate limiting occurs in multiple layers: connection-level limits in the API route middleware, token-quota checks in modelLifecyclePolicy.ts, and per-organization limits in upstream provider configuration. For custom rate-limit logic, extend modelLifecyclePolicy.ts before the executor call.

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