# openai/openai-node architecture

> Architecture diagram of the GitHub repository openai/openai-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/openai-node
- Repository: https://github.com/openai/openai-node

## Overview

This repository is the source for the OpenAI JavaScript/TypeScript SDK, not an application. Its architecture is centered on a generated API surface that wraps OpenAI’s REST and realtime APIs and exposes them through a small set of shared HTTP/runtime primitives.

High-level structure

- Public entrypoint and package surface
  - `src/index.ts` is the main SDK entrypoint exported as `openai`.
  - It re-exports the main client classes, resource namespaces, helpers, error types, and version metadata.
  - The README shows two primary client families:
    - `OpenAI` for the core OpenAI API
    - `AzureOpenAI` for Azure OpenAI, which has a slightly different request/response shape and auth model

- Generated API resources
  - Most of `src/resources/**` is a generated hierarchy of REST API namespaces.
  - These are organized by endpoint families such as:
    - `chat`, `responses`, `completions`
    - `audio` (`speech`, `transcriptions`, `translations`)
    - `files`, `uploads`, `images`, `models`, `embeddings`, `moderations`
    - `fine-tuning`, `batches`, `vector-stores`, `containers`
    - `beta` features such as `assistants`, `threads`, `runs`, `chatkit`
    - `realtime`, `webhooks`, `skills`, `conversations`, `evals`, `videos`
  - Each folder typically contains:
    - a namespace wrapper
    - one or more resource classes
    - request/response type definitions and path-specific methods
  - The `api.md` file and `src/resources/**/api.md` files are the generated API reference artifacts for these namespaces.

- Core transport and API plumbing
  - `src/core/**` contains reusable base abstractions used by all resources:
    - `resource.ts` and `api-promise.ts` define the request wrapper pattern
    - `pagination.ts` implements list paging
    - `streaming.ts` implements SSE/stream handling
    - `uploads.ts` handles file upload abstractions
    - `error.ts` defines API error classes
    - `EventEmitter.ts` is used for evented streaming APIs
  - `src/internal/**` contains lower-level runtime utilities:
    - request construction, headers, querystring, path handling
    - stream decoding and line parsing
    - platform/runtime detection
    - type shims for different environments
    - file and bytes helpers
    - logging, env, UUID, and other small utilities
  - `src/internal/qs/**` is a vendored querystring implementation used to serialize complex request params consistently across runtimes.

- Streaming and event-driven subsystems
  - There are two major streaming paths:
    - Server-Sent Events for the Responses/Chat APIs, implemented through `src/core/streaming.ts` and the `src/lib/*Stream.ts` classes
    - WebSocket-based realtime APIs in `src/realtime/**` and `src/beta/realtime/**`
  - The stream layer turns HTTP/event frames into typed events and user-facing iterators or event emitters.
  - `src/lib/ResponseStream.ts`, `ChatCompletionStream.ts`, `AssistantStream.ts`, and related classes are higher-level orchestration layers that consume stream frames and expose convenience methods for incremental text, tool calls, and structured events.
  - The realtime subsystem is a separate boundary from REST:
    - `src/realtime/**` is the core realtime client
    - `src/beta/realtime/**` is the beta/realtime namespace exposed under the broader API surface
    - Both support WebSocket transport and event emission for low-latency multimodal interactions.

- Higher-level orchestration and parsing
  - `src/lib/**` contains client-side helpers that sit above raw REST calls:
    - chat/realtime parsing utilities
    - tool-call runners
    - function execution helpers
    - JSON schema and structured output helpers
    - transforms between raw API events and ergonomic SDK abstractions
  - These are not the transport layer; they interpret model outputs and manage control flow for streaming, parsing, and tool invocation.

- Helper modules exposed to consumers
  - `src/helpers/**` contains public convenience helpers:
    - audio helpers
    - Zod integration for schema-driven parsing/validation
  - These are optional layer-on-top utilities, not required for basic API calls.

- Azure-specific client path
  - `src/azure.ts` provides the Azure OpenAI client and configuration differences.
  - The README highlights this as a separate constructor because Azure uses its own auth, endpoints, and model deployment conventions.
  - This is an important architectural boundary: the SDK supports both the standard OpenAI API and Azure OpenAI through a shared core, but with distinct client setup and request shaping.

Request/data flow

- A consumer imports `OpenAI` or `AzureOpenAI` from the package entrypoint.
- The client instance is configured with auth, timeout, retry, logging, fetch, and runtime-specific options.
- A method on a resource namespace is invoked, for example `client.responses.create(...)`.
- The resource method uses shared core request helpers to:
  - build the path and query/body
  - serialize uploads or multipart payloads when needed
  - attach headers, auth, and request options
  - send the request through the configured `fetch`
- The response flows back through common parsing logic:
  - JSON bodies are parsed into typed objects
  - errors are mapped to SDK error subclasses
  - request IDs from response headers are attached as `_request_id`
  - paginated endpoints are wrapped in iterable page abstractions
  - streaming responses are converted into async iterables / event emitters / stream objects
- For realtime WebSocket use cases, the flow bypasses standard REST request/response handling and instead:
  - opens a WebSocket connection
  - emits typed events
  - receives incremental audio/text/function-call updates

Platform and runtime boundaries

- The SDK is designed to run across multiple environments:
  - Node.js
  - Deno
  - Bun
  - Cloudflare Workers
  - Vercel Edge
  - browsers, but only when explicitly enabled with `dangerouslyAllowBrowser`
- `src/internal/detect-platform.ts`, `src/internal/shims.ts`, and `src/internal/shim-types.ts` are part of the runtime-adaptation layer.
- The repo includes environment-specific tests and examples because the same SDK surface has to behave correctly under different `fetch`, stream, and file APIs.

Testing architecture

- `tests/**` contains the main verification suite for the SDK itself.
  - There are focused unit tests for internal utilities, streaming behavior, pagination, uploads, parsing, and helpers.
  - `tests/api-resources/**` mirrors the resource tree and validates request construction and endpoint behavior per API family.
  - `tests/lib/**` covers the higher-level orchestration and streaming abstractions.
  - Mocking utilities live under `tests/utils/**`.
- The tests are broad because the SDK’s main risk is not business logic; it is incorrect API surface generation, serialization, streaming semantics, or runtime incompatibility.

Compatibility and ecosystem testing

- `ecosystem-tests/**` is a major architectural component of the repository.
  - It contains many small fixture projects for different runtime/tooling combinations:
    - Node CommonJS and ESM
    - TypeScript with different module resolution modes
    - Bun
    - Deno
    - browser direct import
    - Cloudflare Workers
    - Vercel Edge
    - webpack-based browser bundle tests
  - These projects validate that the published package works in real consumer environments, not just in unit tests.
  - This is a strong sign that cross-runtime compatibility is a first-class architectural requirement.

Release and packaging pipeline

- The repository is built and released as a package, not deployed as a service.
- Important build/release tooling lives in:
  - `scripts/**` for build, format, lint, test, publish, and release automation
  - `bin/**` for CLI-style release and publish helpers
  - `.github/workflows/**` for CI, release creation, changelog/release-please, and publish jobs
- The presence of both npm and JSR publishing workflows indicates that the SDK is published to multiple package registries.
- `tsconfig.*.json`, `jest.config.ts`, `eslint.config.mjs`, `prettier` config, and `package.json` together define the development/build/test pipeline.

Important architectural boundaries to diagram

1. Public package boundary
   - External consumers import from `src/index.ts` through the published package name.

2. Client boundary
   - `OpenAI` and `AzureOpenAI` are the two top-level clients.
   - They share infrastructure but differ in auth, endpoints, and some API shape assumptions.

3. Resource boundary
   - Each `src/resources/**` subtree is a separate API namespace with its own methods and types.

4. Transport boundary
   - Shared HTTP, streaming, uploads, pagination, logging, errors, and runtime shims are centralized under `src/core` and `src/internal`.

5. Streaming boundary
   - REST JSON responses, SSE streams, and WebSocket realtime traffic are handled by distinct subsystems.

6. Runtime boundary
   - Node, browser, Deno, Bun, edge runtimes, and Worker environments are all supported through adapter/shim layers and ecosystem tests.

7. Tooling/release boundary
   - Build, publish, and compatibility validation are handled by separate scripts and GitHub Actions, not embedded in the library runtime.

In short, this repo is a multi-runtime SDK with a generated REST API surface, shared request/streaming infrastructure, a separate realtime WebSocket subsystem, and extensive environment compatibility validation. Its architecture is optimized around consistent API access across many JavaScript runtimes rather than around a single application server or frontend.

Main entry points: [`src/core/resource.ts`](https://github.com/openai/openai-node/blob/HEAD/src/core/resource.ts) (Core base), [`src/index.ts`](https://github.com/openai/openai-node/blob/HEAD/src/index.ts) (SDK entry), [`src/client.ts`](https://github.com/openai/openai-node/blob/HEAD/src/client.ts) (OpenAI client), [`src/resources.ts`](https://github.com/openai/openai-node/blob/HEAD/src/resources.ts) (Resource map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Public package"
  src_index["SDK entry<br/>entrypoint<br/>[index.ts]"]
  client["OpenAI client<br/>[client.ts]"]
  azure["Azure client<br/>[azure.ts]"]
  helpers_zod["Schema helpers<br/>[zod.ts]"]
end

subgraph "Runtime core"
  core_base["Core base<br/>transport base<br/>[resource.ts]"]
  core_promise["API promise<br/>transport helper<br/>[api-promise.ts]"]
  core_stream["Streaming core<br/>SSE stream<br/>[streaming.ts]"]
  internal_runtime["Runtime shims<br/>platform adapter<br/>[shims.ts]"]
  internal_qs["Querystring<br/>serializer<br/>[index.ts]"]
  lib_orchestrators["Stream runners<br/>orchestration"]
  src_realtime["Realtime core<br/>websocket runtime<br/>[index.ts]"]
end

subgraph "API surface"
  resources_registry["Resource map<br/>namespace index<br/>[resources.ts]"]
  resources_rest["REST resources<br/>generated API<br/>[responses.ts]"]
  resources_beta["Beta APIs<br/>generated API<br/>[beta.ts]"]
  resources_realtime["Realtime API<br/>websocket API<br/>[realtime.ts]"]
  beta_realtime["Beta realtime<br/>websocket API<br/>[index.ts]"]
end

subgraph "Validation"
  tests_suite["SDK tests<br/>test suite<br/>[index.test.ts]"]
  ecosystem["Ecosystem tests<br/>compatibility<br/>[cli.ts]"]
end

subgraph "Release tooling"
  scripts_release["Build scripts<br/>automation"]
  bin_cli["Release CLI<br/>automation"]
  github_ci["CI workflows<br/>automation<br/>[ci.yml]"]
end

src_index -->|"exports"| client
src_index -->|"exports"| azure
src_index -->|"re-exports"| resources_registry
src_index -->|"re-exports"| helpers_zod
src_index -->|"re-exports"| core_base
client -->|"uses"| core_base
client -->|"uses"| internal_runtime
client -->|"hosts"| resources_rest
client -->|"hosts"| resources_beta
azure -->|"shares core"| core_base
azure -->|"adapts"| internal_runtime
resources_registry -->|"maps to"| resources_rest
resources_registry -->|"maps to"| resources_beta
resources_registry -->|"maps to"| resources_realtime
resources_rest -->|"extends"| core_base
resources_beta -->|"extends"| core_base
resources_realtime -->|"wraps"| src_realtime
beta_realtime -->|"wraps"| src_realtime
core_base -->|"uses"| core_promise
core_base -->|"uses"| core_stream
core_base -->|"serializes"| internal_qs
core_base -->|"depends on"| internal_runtime
lib_orchestrators -->|"consumes"| core_stream
lib_orchestrators -->|"orchestrates"| core_base
helpers_zod -->|"supports"| lib_orchestrators
tests_suite -->|"verifies"| core_base
tests_suite -->|"verifies"| resources_rest
tests_suite -->|"verifies"| lib_orchestrators
ecosystem -->|"compatibility"| src_index
scripts_release -->|"drives"| bin_cli
scripts_release -->|"supports"| github_ci
github_ci -->|"runs"| ecosystem
github_ci -->|"runs"| tests_suite

click src_index "https://github.com/openai/openai-node/blob/master/src/index.ts"
click client "https://github.com/openai/openai-node/blob/master/src/client.ts"
click azure "https://github.com/openai/openai-node/blob/master/src/azure.ts"
click resources_registry "https://github.com/openai/openai-node/blob/master/src/resources.ts"
click core_base "https://github.com/openai/openai-node/blob/master/src/core/resource.ts"
click core_promise "https://github.com/openai/openai-node/blob/master/src/core/api-promise.ts"
click core_stream "https://github.com/openai/openai-node/blob/master/src/core/streaming.ts"
click internal_runtime "https://github.com/openai/openai-node/blob/master/src/internal/shims.ts"
click internal_qs "https://github.com/openai/openai-node/blob/master/src/internal/qs/index.ts"
click lib_orchestrators "https://github.com/openai/openai-node/blob/master/src/lib/ChatCompletionStream.ts"
click helpers_zod "https://github.com/openai/openai-node/blob/master/src/helpers/zod.ts"
click resources_rest "https://github.com/openai/openai-node/blob/master/src/resources/responses.ts"
click resources_beta "https://github.com/openai/openai-node/blob/master/src/resources/beta.ts"
click resources_realtime "https://github.com/openai/openai-node/blob/master/src/resources/realtime.ts"
click src_realtime "https://github.com/openai/openai-node/blob/master/src/realtime/index.ts"
click beta_realtime "https://github.com/openai/openai-node/blob/master/src/beta/realtime/index.ts"
click tests_suite "https://github.com/openai/openai-node/blob/master/tests/index.test.ts"
click ecosystem "https://github.com/openai/openai-node/blob/master/ecosystem-tests/cli.ts"
click scripts_release "https://github.com/openai/openai-node/tree/master/scripts/build"
click bin_cli "https://github.com/openai/openai-node/tree/master/bin/cli"
click github_ci "https://github.com/openai/openai-node/blob/master/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class src_index,client,azure,helpers_zod toneBlue
class core_base,core_promise,core_stream,internal_runtime,internal_qs,lib_orchestrators,src_realtime toneAmber
class resources_registry,resources_rest,resources_beta,resources_realtime,beta_realtime toneMint
class tests_suite,ecosystem toneRose
class scripts_release,bin_cli,github_ci toneIndigo
```

## Components

### Public package

Package entrypoints and exported client surface.

- [SDK entry](https://github.com/openai/openai-node/blob/HEAD/src/index.ts): entrypoint · Main package export surface for consumers. · `src/index.ts`
- [OpenAI client](https://github.com/openai/openai-node/blob/HEAD/src/client.ts): client · Primary OpenAI API client configuration and request orchestration. · `src/client.ts`
- [Azure client](https://github.com/openai/openai-node/blob/HEAD/src/azure.ts): client · Azure OpenAI client with alternate auth and endpoint shaping. · `src/azure.ts`
- [Schema helpers](https://github.com/openai/openai-node/blob/HEAD/src/helpers/zod.ts): helper · Public helper layer for structured parsing and validation. · `src/helpers/zod.ts`

### Runtime core

Shared transport, parsing, streaming, and environment-adaptation primitives.

- [Core base](https://github.com/openai/openai-node/blob/HEAD/src/core/resource.ts): transport base · Shared request wrapper, pagination, uploads, errors, and streaming plumbing. · `src/core/resource.ts`
- [API promise](https://github.com/openai/openai-node/blob/HEAD/src/core/api-promise.ts): transport helper · Async request wrapper and response handling abstraction. · `src/core/api-promise.ts`
- [Streaming core](https://github.com/openai/openai-node/blob/HEAD/src/core/streaming.ts): SSE stream · Server-sent event parsing and typed stream conversion. · `src/core/streaming.ts`
- [Runtime shims](https://github.com/openai/openai-node/blob/HEAD/src/internal/shims.ts): platform adapter · Environment detection, shims, headers, query, and low-level helpers. · `src/internal/shims.ts`
- [Querystring](https://github.com/openai/openai-node/blob/HEAD/src/internal/qs/index.ts): serializer · Vendored querystring serialization for cross-runtime consistency. · `src/internal/qs/index.ts`
- [Stream runners](https://github.com/openai/openai-node/blob/HEAD/src/lib/ChatCompletionStream.ts): orchestration · Higher-level chat, responses, and tool-calling orchestration layers. · `src/lib/ChatCompletionStream.ts`
- [Realtime core](https://github.com/openai/openai-node/blob/HEAD/src/realtime/index.ts): websocket runtime · Lower-level realtime transport and event handling. · `src/realtime/index.ts`

### API surface

Generated REST namespaces plus realtime boundaries.

- [Resource map](https://github.com/openai/openai-node/blob/HEAD/src/resources.ts): namespace index · Top-level resource namespace aggregator. · `src/resources.ts`
- [REST resources](https://github.com/openai/openai-node/blob/HEAD/src/resources/responses.ts): generated API · Generated REST namespace tree for core OpenAI endpoints. · `src/resources/responses.ts`
- [Beta APIs](https://github.com/openai/openai-node/blob/HEAD/src/resources/beta.ts): generated API · Beta feature namespaces including assistants, threads, and chatkit. · `src/resources/beta.ts`
- [Realtime API](https://github.com/openai/openai-node/blob/HEAD/src/resources/realtime.ts): websocket API · WebSocket-oriented realtime client surface. · `src/resources/realtime.ts`
- [Beta realtime](https://github.com/openai/openai-node/blob/HEAD/src/beta/realtime/index.ts): websocket API · Beta realtime namespace built on the realtime core. · `src/beta/realtime/index.ts`

### Validation

Unit, resource, and ecosystem compatibility tests.

- [SDK tests](https://github.com/openai/openai-node/blob/HEAD/tests/index.test.ts): test suite · Main unit and resource behavior verification. · `tests/index.test.ts`
- [Ecosystem tests](https://github.com/openai/openai-node/blob/HEAD/ecosystem-tests/cli.ts): compatibility · Real-world runtime and bundler compatibility fixtures. · `ecosystem-tests/cli.ts`

### Release tooling

Scripts, CLI helpers, and CI/release automation.

- [Build scripts](https://github.com/openai/openai-node/tree/HEAD/scripts/build): automation · Build, lint, test, and release automation scripts. · `scripts/build`
- [Release CLI](https://github.com/openai/openai-node/tree/HEAD/bin/cli): automation · Publish and release helper commands. · `bin/cli`
- [CI workflows](https://github.com/openai/openai-node/blob/HEAD/.github/workflows/ci.yml): automation · GitHub Actions workflows for CI, release, and publishing. · `.github/workflows/ci.yml`

## Connections

- SDK entry → OpenAI client: exports · Public entrypoint exposes the primary client.
- SDK entry → Azure client: exports · Public entrypoint exposes Azure client support.
- SDK entry → Resource map: re-exports · Entry surface re-exports resource namespaces.
- SDK entry → Schema helpers: re-exports · Entry surface exposes helper utilities.
- SDK entry → Core base: re-exports · Entry surface exposes core types and errors.
- OpenAI client → Core base: uses · Client delegates request execution to shared core plumbing.
- OpenAI client → Runtime shims: uses · Client configuration depends on runtime shims and low-level helpers.
- OpenAI client → REST resources: hosts · Client instance provides the REST resource namespaces.
- OpenAI client → Beta APIs: hosts · Client instance exposes beta namespaces.
- Azure client → Core base: shares core · Azure client reuses the same transport foundation.
- Azure client → Runtime shims: adapts · Azure client adapts endpoint and auth/runtime behavior.
- Resource map → REST resources: maps to · Top-level namespace registry points into generated REST resources.
- Resource map → Beta APIs: maps to · Top-level namespace registry points into beta resources.
- Resource map → Realtime API: maps to · Top-level registry exposes realtime surface.
- REST resources → Core base: extends · REST namespaces are built on the shared resource base.
- Beta APIs → Core base: extends · Beta namespaces are built on the shared resource base.
- Realtime API → Realtime core: wraps · Realtime resource surface wraps the lower-level realtime runtime.
- Beta realtime → Realtime core: wraps · Beta realtime namespace wraps the shared realtime runtime.
- Core base → API promise: uses · Resource methods use the API promise request wrapper.
- Core base → Streaming core: uses · Shared core routes streaming responses through SSE handling.
- Core base → Querystring: serializes · Core request building uses vendored querystring serialization.
- Core base → Runtime shims: depends on · Core abstractions depend on runtime utilities and shims.
- Stream runners → Streaming core: consumes · Higher-level runners consume core stream frames.
- Stream runners → Core base: orchestrates · Orchestration layers sit above raw transport calls.
- Schema helpers → Stream runners: supports · Helpers feed structured parsing and tool-oriented orchestration.
- SDK tests → Core base: verifies · Unit and resource tests validate the shared SDK core.
- SDK tests → REST resources: verifies · Tests exercise generated REST namespaces.
- SDK tests → Stream runners: verifies · Tests cover higher-level runners and parsers.
- Ecosystem tests → SDK entry: compatibility · Fixture projects validate published package imports across runtimes.
- Build scripts → Release CLI: drives · Build and release scripts invoke CLI helpers.
- Build scripts → CI workflows: supports · Repository automation underpins CI and release workflows.
- CI workflows → Ecosystem tests: runs · CI includes compatibility validation across environments.
- CI workflows → SDK tests: runs · CI executes the main SDK test suite.
