# apple/apple-ads-platform-api-swift architecture

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

- Interactive diagram: https://gitdiagram.com/apple/apple-ads-platform-api-swift
- Repository: https://github.com/apple/apple-ads-platform-api-swift

## Overview

AppleAdsClient is a Swift client library for the Apple Ads Platform API. An application configures a client, then calls generated API operations; the client assembles middleware that attaches authentication and request metadata before sending requests to Apple. In managed key-based authentication, it signs a client-secret JWT, exchanges it for an access token, and caches/refreshes that token; custom secret and token providers are supported alternatives. The README also documents configuration-from-environment and long-running service use. The graph reflects the sampled connection and middleware code; generated endpoint internals and some documented capabilities were not sampled.

Main entry points: [`Sources/AppleAdsClient/AppleAdsClient.swift`](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClient.swift) (AppleAdsClient), [`Sources/AppleAdsClient/AccessTokenFetcher.swift`](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AccessTokenFetcher.swift) (Access token fetcher), [`Sources/AppleAdsClient/Generated/Client.swift`](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Generated/Client.swift) (Generated operations), [`Sources/AppleAdsClient/Auth/CachingTokenProvider.swift`](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/CachingTokenProvider.swift) (Caching token provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and API"]
  node_client["AppleAdsClient"]
  node_operations["Generated operations<br/>[Client.swift]"]
  node_models["API models<br/>[Types.swift]"]
  node_context["Ad account context<br/>[XApContext.swift]"]
  node_datecodec["Date transcoder"]
end

subgraph group_auth["Authentication"]
  node_tokenprovider["Token provider"]
  node_cache["Caching token provider"]
  node_fetcher["Access token fetcher"]
  node_signer["JWT signer<br/>[JWTSigner.swift]"]
  node_secretprovider["Client secret provider"]
end

subgraph group_middleware["Request middleware"]
  node_authmiddleware["Auth middleware"]
  node_usermiddleware["User-Agent middleware"]
  node_headermiddleware["Header fixup"]
end

subgraph group_configuration["Configuration and lifecycle"]
  node_configuration["Client configuration"]
  node_configreader["Config reader"]
  node_service["Service lifecycle"]
end

node_app(("Application"))
node_adsapi{{"Apple Ads API"}}
node_oauth{{"OAuth endpoint"}}

node_app -->|"sets options"| node_configuration
node_app -->|"creates and calls"| node_client
node_configreader -.->|"reads values"| node_configuration
node_client -->|"constructs client"| node_operations
node_client -->|"creates managed cache"| node_cache
node_client -->|"creates fetcher"| node_fetcher
node_client -->|"creates signer"| node_signer
node_client -->|"installs middleware"| node_authmiddleware
node_client -->|"installs middleware"| node_usermiddleware
node_client -->|"installs middleware"| node_headermiddleware
node_client -->|"configures transcoder"| node_datecodec
node_client -.->|"supports service use"| node_service
node_operations -->|"sends API requests"| node_adsapi
node_operations -->|"uses API types"| node_models
node_authmiddleware -->|"requests bearer token"| node_tokenprovider
node_cache -->|"fetches and refreshes"| node_fetcher
node_fetcher -.->|"signs client secret"| node_signer
node_fetcher -.->|"requests client secret"| node_secretprovider
node_fetcher -->|"exchanges credentials"| node_oauth
node_app -->|"builds account header"| node_context

click node_configuration "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClientConfiguration.swift"
click node_configreader "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClientConfiguration%2BConfigReader.swift"
click node_client "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClient.swift"
click node_operations "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Generated/Client.swift"
click node_models "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Generated/Types.swift"
click node_authmiddleware "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AuthMiddleware.swift"
click node_usermiddleware "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/UserAgentMiddleware.swift"
click node_headermiddleware "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/HeaderFixupMiddleware.swift"
click node_tokenprovider "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/TokenProvider.swift"
click node_cache "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/CachingTokenProvider.swift"
click node_fetcher "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AccessTokenFetcher.swift"
click node_signer "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/JWTSigner.swift"
click node_secretprovider "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/ClientSecretProvider.swift"
click node_context "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/XApContext.swift"
click node_datecodec "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsDateTranscoder.swift"
click node_service "https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClient.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_client,node_operations,node_models,node_context,node_datecodec toneBlue
class node_tokenprovider,node_cache,node_fetcher,node_signer,node_secretprovider toneAmber
class node_authmiddleware,node_usermiddleware,node_headermiddleware,node_adsapi toneMint
class node_configuration,node_configreader,node_service toneRose
class node_app,node_oauth toneIndigo
```

## Components

### Client and API

- [AppleAdsClient](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClient.swift): `Sources/AppleAdsClient/AppleAdsClient.swift`
- [Generated operations](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Generated/Client.swift): `Sources/AppleAdsClient/Generated/Client.swift`
- [API models](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Generated/Types.swift): `Sources/AppleAdsClient/Generated/Types.swift`
- [Ad account context](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/XApContext.swift): `Sources/AppleAdsClient/XApContext.swift`
- [Date transcoder](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsDateTranscoder.swift): `Sources/AppleAdsClient/AppleAdsDateTranscoder.swift`

### Authentication

- [Token provider](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/TokenProvider.swift): `Sources/AppleAdsClient/Auth/TokenProvider.swift`
- [Caching token provider](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/CachingTokenProvider.swift): `Sources/AppleAdsClient/Auth/CachingTokenProvider.swift`
- [Access token fetcher](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AccessTokenFetcher.swift): `Sources/AppleAdsClient/AccessTokenFetcher.swift`
- [JWT signer](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/JWTSigner.swift): `Sources/AppleAdsClient/Auth/JWTSigner.swift`
- [Client secret provider](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/Auth/ClientSecretProvider.swift): `Sources/AppleAdsClient/Auth/ClientSecretProvider.swift`

### Request middleware

- [Auth middleware](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AuthMiddleware.swift): `Sources/AppleAdsClient/AuthMiddleware.swift`
- [User-Agent middleware](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/UserAgentMiddleware.swift): `Sources/AppleAdsClient/UserAgentMiddleware.swift`
- [Header fixup](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/HeaderFixupMiddleware.swift): `Sources/AppleAdsClient/HeaderFixupMiddleware.swift`

### Configuration and lifecycle

- [Client configuration](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClientConfiguration.swift): `Sources/AppleAdsClient/AppleAdsClientConfiguration.swift`
- [Config reader](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClientConfiguration%2BConfigReader.swift): `Sources/AppleAdsClient/AppleAdsClientConfiguration+ConfigReader.swift`
- [Service lifecycle](https://github.com/apple/apple-ads-platform-api-swift/blob/main/Sources/AppleAdsClient/AppleAdsClient.swift): `Sources/AppleAdsClient/AppleAdsClient.swift`

### Other components

- **Application**
- **Apple Ads API**
- **OAuth endpoint**

## Connections

- Application → Client configuration: sets options
- Application → AppleAdsClient: creates and calls
- Config reader → Client configuration: reads values
- AppleAdsClient → Generated operations: constructs client
- AppleAdsClient → Caching token provider: creates managed cache
- AppleAdsClient → Access token fetcher: creates fetcher
- AppleAdsClient → JWT signer: creates signer
- AppleAdsClient → Auth middleware: installs middleware
- AppleAdsClient → User-Agent middleware: installs middleware
- AppleAdsClient → Header fixup: installs middleware
- AppleAdsClient → Date transcoder: configures transcoder
- AppleAdsClient → Service lifecycle: supports service use
- Generated operations → Apple Ads API: sends API requests
- Generated operations → API models: uses API types
- Auth middleware → Token provider: requests bearer token
- Caching token provider → Access token fetcher: fetches and refreshes
- Access token fetcher → JWT signer: signs client secret
- Access token fetcher → Client secret provider: requests client secret
- Access token fetcher → OAuth endpoint: exchanges credentials
- Application → Ad account context: builds account header