# gouwsxander/apple-intelligence-api architecture

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

- Interactive diagram: https://gitdiagram.com/gouwsxander/apple-intelligence-api
- Repository: https://github.com/gouwsxander/apple-intelligence-api

## Overview

This is a Vapor HTTP wrapper for Apple’s on-device Foundation Models, exposing an OpenAI-compatible API. A client posts a prompt or conversation; routing decodes the request, constructs a model session, selects ordinary or streaming response generation, and returns completion data or SSE chunks. The documented surface also includes model listing and structured JSON-schema outputs. Setup and inference wiring are shown in the excerpts; the streaming and structured-output branches are implemented in the sampled session and response-generator modules. No database-backed product behavior is evident despite database configuration.

Main entry points: [`Sources/AppleIntelligenceApi/routes.swift`](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/routes.swift) (API routes), [`Sources/AppleIntelligenceApi/Utils/ResponseSession.swift`](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/ResponseSession.swift) (Inference session), [`Sources/AppleIntelligenceApi/Utils/RequestContent.swift`](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/RequestContent.swift) (Request schema), [`Sources/AppleIntelligenceApi/entrypoint.swift`](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/entrypoint.swift) (Server entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_entry["Server entrypoint<br/>[entrypoint.swift]"]
  node_setup["App configuration<br/>[configure.swift]"]
  node_routes["API routes<br/>[routes.swift]"]
end

subgraph group_contract["Request and response types"]
  node_request["Request schema"]
  node_models["Model listing types<br/>[Models.swift]"]
  node_errors["API errors<br/>[AbortErrors.swift]"]
end

subgraph group_inference["Model inference"]
  node_session["Inference session"]
  node_foundation{{"Foundation Models"}}
end

subgraph group_output["Response formatting"]
  node_generator["Response selection"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_entry
node_entry -->|"configures app"| node_setup
node_setup -->|"registers routes"| node_routes
node_client -->|"calls API"| node_routes
node_routes -->|"decodes body"| node_request
node_routes -->|"creates session"| node_session
node_session -->|"reads options"| node_request
node_session -->|"runs generation"| node_foundation
node_routes -->|"selects formatter"| node_generator
node_generator -->|"gets response"| node_session
node_routes -->|"returns model list"| node_models
node_request -->|"defines structured output"| node_session

click node_entry "https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/entrypoint.swift"
click node_setup "https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/configure.swift"
click node_routes "https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/routes.swift"
click node_request "https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/RequestContent.swift"
click node_models "https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/Models.swift"
click node_session "https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/ResponseSession.swift"
click node_generator "https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/ResponseGenerator.swift"
click node_errors "https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/AbortErrors.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_entry,node_setup,node_routes,node_client toneBlue
class node_request,node_models,node_errors toneAmber
class node_session,node_foundation toneMint
class node_generator toneRose
```

## Components

### HTTP API

- [Server entrypoint](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/entrypoint.swift): `Sources/AppleIntelligenceApi/entrypoint.swift`
- [App configuration](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/configure.swift): `Sources/AppleIntelligenceApi/configure.swift`
- [API routes](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/routes.swift): `Sources/AppleIntelligenceApi/routes.swift`

### Request and response types

- [Request schema](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/RequestContent.swift): `Sources/AppleIntelligenceApi/Utils/RequestContent.swift`
- [Model listing types](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/Models.swift): `Sources/AppleIntelligenceApi/Utils/Models.swift`
- [API errors](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/AbortErrors.swift): `Sources/AppleIntelligenceApi/Utils/AbortErrors.swift`

### Model inference

- [Inference session](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/ResponseSession.swift): `Sources/AppleIntelligenceApi/Utils/ResponseSession.swift`
- **Foundation Models**

### Response formatting

- [Response selection](https://github.com/gouwsxander/apple-intelligence-api/blob/master/Sources/AppleIntelligenceApi/Utils/ResponseGenerator.swift): `Sources/AppleIntelligenceApi/Utils/ResponseGenerator.swift`

### Other components

- **API client**

## Connections

- API client → Server entrypoint: sends requests (evidence: `README.md`)
- Server entrypoint → App configuration: configures app (evidence: `Sources/AppleIntelligenceApi/entrypoint.swift`)
- App configuration → API routes: registers routes (evidence: `Sources/AppleIntelligenceApi/configure.swift`)
- API client → API routes: calls API (evidence: `README.md`)
- API routes → Request schema: decodes body (evidence: `Sources/AppleIntelligenceApi/routes.swift`)
- API routes → Inference session: creates session (evidence: `Sources/AppleIntelligenceApi/routes.swift`)
- Inference session → Request schema: reads options (evidence: `Sources/AppleIntelligenceApi/Utils/ResponseSession.swift`)
- Inference session → Foundation Models: runs generation (evidence: `Sources/AppleIntelligenceApi/Utils/ResponseSession.swift`)
- API routes → Response selection: selects formatter (evidence: `Sources/AppleIntelligenceApi/routes.swift`)
- Response selection → Inference session: gets response (evidence: `Sources/AppleIntelligenceApi/Utils/ResponseGenerator.swift`)
- API routes → Model listing types: returns model list (evidence: `Sources/AppleIntelligenceApi/routes.swift`)
- Request schema → Inference session: defines structured output (evidence: `Sources/AppleIntelligenceApi/Utils/RequestContent.swift`)
