Architecture Overview

GodeX is a gateway that translates OpenAI Responses API requests into Chat Completions API calls for any configured upstream provider. It follows a layered architecture with clear separation of concerns: protocol handling at the boundary, bridge logic in the middle, and provider-specific code isolated in specs and hooks.

This page has two complementary views: the request lifecycle (how a single request flows through the system) and the component model (what the building blocks are and how they depend on each other). Understanding both is essential for debugging compatibility issues, adding new providers, or extending the bridge.

At a Glance

Layer	Component	Responsibility
CLI	serve	Bootstraps config, registrar, ApplicationContext, and Bun server
Application	ApplicationContext	Holds config, resolver, registrar, session store, trace recorder
Application	ApplicationServices	Factory that wires logger, ModelResolver, Registrar, ResponsesBridgeRuntime
Server	createBuiltinRoutes	Maps /health, /v1/models, /v1/responses to handlers
Route	handleResponses	Parses request, creates ResponsesContext, dispatches
Context	ResponsesContext	Per-request state: resolved model, provider, session, diagnostics
Bridge	ProviderExchange	Builds Chat Completion request, calls upstream, records traces
Bridge	ResponsesBridgeRuntime	Selects sync or stream pipeline
Provider	Registrar	Manages ProviderEdge factories and resolved instances
Resolver	ModelResolver	Maps model selectors to (provider, model) pairs

Request Lifecycle

Core Types

Startup Sequence

Request Processing Sequence

Bridge Pipeline Detail

The bridge pipeline inside ProviderExchange follows a fixed sequence. Each step contributes decisions and data that downstream steps consume:

Step	Function	Output
1	planBridgeCompatibility	Compatibility plan with parameter decisions
2	planTools	Tool declarations, tool_choice, tool decisions
3	planOutputContract	Response format plan (native, degraded, or synthetic)
4	normalizeCurrentInput + normalizeResponseItems	Normalized ChatCompletionMessageParam[]
5	buildChatMessages	Merged assistant messages with tool calls
6	applyTools	request.tools and request.tool_choice
7	applyRequestOptions	stream, temperature, top_p, max_tokens, reasoning

System Components

The full request path connects every layer — from the Bun server routes through the bridge request builder, the provider edge, and the reconstruction layer:

The core domain types and their relationships:

Layer Responsibilities

Layer	Module	Role
Server	src/server/	HTTP routing, request parsing, SSE encoding, error handling
Context	src/context/	ApplicationContext (app-wide services) and ResponsesContext (per-request state)
Bridge	src/bridge/	Provider-agnostic Responses-to-Chat planning and reconstruction
Responses	src/responses/	Sync and stream orchestration pipelines around the bridge
Provider	src/providers/	Provider-specific specs, hooks, clients, and registry
Session	src/session/	History persistence and previous_response_id chain resolution
Resolver	src/resolver/	Model alias and provider/model selector resolution
Config	src/config/	YAML schema, env interpolation, defaults, validation
Error	src/error/	Structured error hierarchy with domain codes

Dependency Flow

Cross-References

• Compatibility: How the bridge plans feature compatibility before building a request
• Request Building: Step-by-step conversion from Responses to Chat Completions
• Response Reconstruction: How upstream responses are mapped back to the Responses API shape

References

• src/cli/serve.ts:12-62 -- CLI entry point, server bootstrap, and shutdown handlers
• src/context/application-context.ts:10-40 -- ApplicationContext class holding all shared services
• src/context/application-services.ts:1-48 -- Factory wiring logger, resolver, registrar, bridge runtime
• src/server/server.ts:21-51 -- Route map creation and Bun server startup
• src/server/routes/responses/handler.ts:1-33 -- Responses route handler with parse, context creation, and dispatch
• src/responses/runtime.ts:19-41 -- ResponsesBridgeRuntime delegating to sync and stream pipelines
• src/responses/provider-exchange.ts:1-166 -- ProviderExchange orchestrating request building and upstream calls
• src/providers/registrar.ts:1-95 -- Provider factory registration and resolution
• src/resolver/model-resolver.ts:1-37 -- Model selector parsing and alias resolution