# macpaw/openai architecture

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

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

## Overview

This is a Swift client SDK for OpenAI-compatible APIs, with a small SwiftUI demo. The principal workflow is: an application configures the SDK, invokes an API capability with a typed query, and receives a decoded result or streamed events through async, closure-based, or Combine interfaces. The README documents broad API coverage; the sampled source confirms request building, middleware interception, transport, and streaming behavior. Endpoint-to-request wiring is not fully sampled, so the graph leaves that internal connection unspecified.

Main entry points: [`Sources/OpenAI/Private/Client/AsyncClient.swift`](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/AsyncClient.swift) (Async transport), [`Sources/OpenAI/Private/Client/StreamingClient.swift`](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/StreamingClient.swift) (Streaming transport), [`Sources/OpenAI/Private/URLRequestBuildable.swift`](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/URLRequestBuildable.swift) (Request building), [`Sources/OpenAI/Public/Protocols/OpenAIProtocol.swift`](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Protocols/OpenAIProtocol.swift) (Client protocols)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["SDK entry"]
  node_openai["OpenAI client<br/>[OpenAI.swift]"]
  node_protocol["Client protocols"]
  node_concurrency["Client interfaces"]
end

subgraph group_capabilities["API capabilities"]
  node_chat["Text and chat<br/>[ChatQuery.swift]"]
  node_responses["Responses API"]
  node_tools["Tools and functions"]
  node_images["Image generation"]
  node_audio["Audio APIs"]
  node_assistants["Assistants and runs"]
  node_specialized["Other APIs"]
end

subgraph group_transport["Request transport"]
  node_request["Request building"]
  node_async["Async transport<br/>[AsyncClient.swift]"]
  node_closure["Closure transport<br/>[Client.swift]"]
  node_combine["Combine transport"]
  node_middleware["Middleware"]
  node_streaming["Streaming transport"]
end

subgraph group_results["Results and streams"]
  node_decoder["Response handling"]
  node_events["Stream interpreters"]
  node_resultmodels["Typed results"]
end

node_application(("Application"))
node_urlsession["URLSession"]

node_application -->|"configures and calls"| node_openai
node_openai -->|"exposes"| node_protocol
node_application -->|"invokes API"| node_protocol
node_protocol -->|"offers interfaces"| node_concurrency
node_application -->|"supplies query"| node_chat
node_application -->|"supplies query"| node_responses
node_application -->|"configures tools"| node_tools
node_application -->|"supplies query"| node_images
node_application -->|"supplies query"| node_audio
node_application -->|"supplies query"| node_assistants
node_application -->|"supplies query"| node_specialized
node_async -->|"builds request"| node_request
node_async -->|"intercepts request"| node_middleware
node_async -->|"sends request"| node_urlsession
node_async -->|"decodes response"| node_decoder
node_closure -->|"builds request"| node_request
node_combine -->|"builds request"| node_request
node_streaming -->|"builds request"| node_request
node_streaming -->|"intercepts request"| node_middleware
node_streaming -->|"opens stream"| node_urlsession
node_streaming -->|"interprets events"| node_events
node_decoder -->|"decodes into"| node_resultmodels

click node_openai "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/OpenAI.swift"
click node_protocol "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Protocols/OpenAIProtocol.swift"
click node_concurrency "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/OpenAI%2BOpenAIAsync.swift"
click node_chat "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/ChatQuery.swift"
click node_responses "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/Responses%20API/CreateModelResponseQuery.swift"
click node_tools "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/Responses%20API/CreateModelResponseQuery.swift"
click node_images "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/ImageEditsQuery.swift"
click node_audio "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/AudioTranscriptionQuery.swift"
click node_assistants "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/AssistantsQuery.swift"
click node_specialized "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/EmbeddingsQuery.swift"
click node_request "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/URLRequestBuildable.swift"
click node_async "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/AsyncClient.swift"
click node_closure "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/Client.swift"
click node_combine "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/CombineClient.swift"
click node_middleware "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Protocols/OpenAIMiddleware.swift"
click node_streaming "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/StreamingClient.swift"
click node_decoder "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/URLResponseHandler.swift"
click node_events "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Streaming/ServerSentEventsStreamInterpreter.swift"
click node_resultmodels "https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/Responses%20API/ResponseObject.swift"

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 node_openai,node_protocol,node_concurrency toneBlue
class node_chat,node_responses,node_tools,node_images,node_audio,node_assistants,node_specialized toneAmber
class node_request,node_async,node_closure,node_combine,node_middleware,node_streaming toneMint
class node_decoder,node_events,node_resultmodels toneRose
class node_application,node_urlsession toneIndigo
```

## Components

### SDK entry

- [OpenAI client](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/OpenAI.swift): `Sources/OpenAI/OpenAI.swift`
- [Client protocols](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Protocols/OpenAIProtocol.swift): `Sources/OpenAI/Public/Protocols/OpenAIProtocol.swift`
- [Client interfaces](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/OpenAI%2BOpenAIAsync.swift): `Sources/OpenAI/OpenAI+OpenAIAsync.swift`

### API capabilities

- [Text and chat](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/ChatQuery.swift): `Sources/OpenAI/Public/Models/ChatQuery.swift`
- [Responses API](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/Responses%20API/CreateModelResponseQuery.swift): `Sources/OpenAI/Public/Models/Responses API/CreateModelResponseQuery.swift`
- [Tools and functions](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/Responses%20API/CreateModelResponseQuery.swift): `Sources/OpenAI/Public/Models/Responses API/CreateModelResponseQuery.swift`
- [Image generation](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/ImageEditsQuery.swift): `Sources/OpenAI/Public/Models/ImageEditsQuery.swift`
- [Audio APIs](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/AudioTranscriptionQuery.swift): `Sources/OpenAI/Public/Models/AudioTranscriptionQuery.swift`
- [Assistants and runs](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/AssistantsQuery.swift): `Sources/OpenAI/Public/Models/AssistantsQuery.swift`
- [Other APIs](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/EmbeddingsQuery.swift): `Sources/OpenAI/Public/Models/EmbeddingsQuery.swift`

### Request transport

- [Request building](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/URLRequestBuildable.swift): `Sources/OpenAI/Private/URLRequestBuildable.swift`
- [Async transport](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/AsyncClient.swift): `Sources/OpenAI/Private/Client/AsyncClient.swift`
- [Closure transport](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/Client.swift): `Sources/OpenAI/Private/Client/Client.swift`
- [Combine transport](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/CombineClient.swift): `Sources/OpenAI/Private/Client/CombineClient.swift`
- [Middleware](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Protocols/OpenAIMiddleware.swift): `Sources/OpenAI/Public/Protocols/OpenAIMiddleware.swift`
- [Streaming transport](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Client/StreamingClient.swift): `Sources/OpenAI/Private/Client/StreamingClient.swift`

### Results and streams

- [Response handling](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/URLResponseHandler.swift): `Sources/OpenAI/Private/URLResponseHandler.swift`
- [Stream interpreters](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Private/Streaming/ServerSentEventsStreamInterpreter.swift): `Sources/OpenAI/Private/Streaming/ServerSentEventsStreamInterpreter.swift`
- [Typed results](https://github.com/macpaw/openai/blob/main/Sources/OpenAI/Public/Models/Responses%20API/ResponseObject.swift): `Sources/OpenAI/Public/Models/Responses API/ResponseObject.swift`

### Other components

- **Application**
- **URLSession**

## Connections

- Application → OpenAI client: configures and calls
- OpenAI client → Client protocols: exposes
- Application → Client protocols: invokes API
- Client protocols → Client interfaces: offers interfaces
- Application → Text and chat: supplies query
- Application → Responses API: supplies query
- Application → Tools and functions: configures tools
- Application → Image generation: supplies query
- Application → Audio APIs: supplies query
- Application → Assistants and runs: supplies query
- Application → Other APIs: supplies query
- Async transport → Request building: builds request
- Async transport → Middleware: intercepts request
- Async transport → URLSession: sends request
- Async transport → Response handling: decodes response
- Closure transport → Request building: builds request
- Combine transport → Request building: builds request
- Streaming transport → Request building: builds request
- Streaming transport → Middleware: intercepts request
- Streaming transport → URLSession: opens stream
- Streaming transport → Stream interpreters: interprets events
- Response handling → Typed results: decodes into