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

> Discover where OmniRoute's core request processing handlers reside. Find key files like chatCore.ts within the open-sse/handlers package to understand request flow.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: internals
- Published: 2026-08-31

---

**OmniRoute's core request-processing handlers live in the `open-sse/handlers` package, with the central orchestration centered in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/streamingPipeline.ts)** — assembles the SSE stream and manages backpressure
- **[`streamFinalize.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/modelLifecyclePolicy.ts), and per-organization limits in upstream provider configuration. For custom rate-limit logic, extend [`modelLifecyclePolicy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/modelLifecyclePolicy.ts) before the executor call.