# dotnet/macios architecture

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

- Interactive diagram: https://gitdiagram.com/dotnet/macios
- Repository: https://github.com/dotnet/macios

## Overview

This repository provides the .NET SDKs for building native iOS, Mac Catalyst, macOS, and tvOS applications. The user-facing path is to author a managed application against platform APIs, which bridge to Apple frameworks through the Objective-C runtime; binding generators support that API surface. The tree also includes app templates and MSBuild tasks for platform-specific build operations. The excerpts show selected runtime, Foundation, generator, and framework-binding behavior, not the full build pipeline, so unsampled subsystem links are omitted or marked unverified.

Main entry points: [`src`](https://github.com/dotnet/macios/tree/main/src) (Platform APIs), [`src/ObjCRuntime/Runtime.cs`](https://github.com/dotnet/macios/blob/main/src/ObjCRuntime/Runtime.cs) (Objective-C runtime), [`src/bgen/Generator.cs`](https://github.com/dotnet/macios/blob/main/src/bgen/Generator.cs) (Binding generator), [`dotnet/Templates`](https://github.com/dotnet/macios/tree/main/dotnet/Templates) (App templates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["App authoring"]
  node_templates["App templates"]
end

subgraph group_bindings["Platform bindings"]
  node_platform_apis["Platform APIs"]
  node_foundation["Foundation types"]
  node_ui_apis["UI frameworks"]
  node_media_apis["Media frameworks"]
  node_other_apis["Apple frameworks"]
  node_bgen["Binding generator<br/>[Generator.cs]"]
  node_attributes["Binding attributes"]
  node_rgen["Rgen model<br/>[Constructor.cs]"]
end

subgraph group_runtime["Managed runtime"]
  node_objc_runtime["Objective-C runtime<br/>[Runtime.cs]"]
  node_native_handles["Native handles<br/>[NativeHandle.cs]"]
  node_runtime_errors["Runtime errors<br/>[ThrowHelper.cs]"]
  node_url_session["HTTP transport"]
end

subgraph group_build["Build integration"]
  node_build_tasks["Apple build tasks<br/>[Tasks]"]
  node_build_messaging["Build messaging<br/>[BuildEngine.cs]"]
end

node_developer(("App developer"))
node_apple_frameworks["Apple frameworks"]

node_developer -.->|"starts from"| node_templates
node_developer -->|"uses APIs"| node_platform_apis
node_templates -.->|"scaffolds apps"| node_platform_apis
node_platform_apis -->|"uses types"| node_foundation
node_platform_apis -.->|"includes UI"| node_ui_apis
node_platform_apis -.->|"includes media"| node_media_apis
node_platform_apis -.->|"includes services"| node_other_apis
node_bgen -->|"reads attributes"| node_attributes
node_bgen -.->|"generates bindings"| node_platform_apis
node_rgen -.->|"models bindings"| node_platform_apis
node_platform_apis -.->|"bridges calls"| node_objc_runtime
node_objc_runtime -->|"constructs wrappers"| node_native_handles
node_objc_runtime -->|"raises errors"| node_runtime_errors
node_foundation -.->|"provides transport"| node_url_session
node_url_session -.->|"sends requests"| node_apple_frameworks
node_build_tasks -.->|"uses messaging"| node_build_messaging

click node_templates "https://github.com/dotnet/macios/tree/main/dotnet/Templates"
click node_platform_apis "https://github.com/dotnet/macios/tree/main/src"
click node_foundation "https://github.com/dotnet/macios/tree/main/src/Foundation"
click node_ui_apis "https://github.com/dotnet/macios/tree/main/src/UIKit"
click node_media_apis "https://github.com/dotnet/macios/tree/main/src/AVFoundation"
click node_other_apis "https://github.com/dotnet/macios/tree/main/src"
click node_bgen "https://github.com/dotnet/macios/blob/main/src/bgen/Generator.cs"
click node_attributes "https://github.com/dotnet/macios/blob/main/src/bgen/AttributeManager.cs"
click node_rgen "https://github.com/dotnet/macios/blob/main/src/rgen/Microsoft.Macios.Generator/DataModel/Constructor.cs"
click node_objc_runtime "https://github.com/dotnet/macios/blob/main/src/ObjCRuntime/Runtime.cs"
click node_native_handles "https://github.com/dotnet/macios/blob/main/src/ObjCRuntime/NativeHandle.cs"
click node_runtime_errors "https://github.com/dotnet/macios/blob/main/src/ObjCRuntime/ThrowHelper.cs"
click node_url_session "https://github.com/dotnet/macios/blob/main/src/Foundation/NSUrlSessionHandler.cs"
click node_build_tasks "https://github.com/dotnet/macios/tree/main/msbuild/Xamarin.MacDev.Tasks/Tasks"
click node_build_messaging "https://github.com/dotnet/macios/blob/main/msbuild/Messaging/Xamarin.Messaging.Build/BuildEngine.cs"

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_templates toneBlue
class node_platform_apis,node_foundation,node_ui_apis,node_media_apis,node_other_apis,node_bgen,node_attributes,node_rgen toneAmber
class node_objc_runtime,node_native_handles,node_runtime_errors,node_url_session toneMint
class node_build_tasks,node_build_messaging toneRose
class node_developer,node_apple_frameworks toneIndigo
```

## Components

### App authoring

- [App templates](https://github.com/dotnet/macios/tree/main/dotnet/Templates): `dotnet/Templates`

### Platform bindings

- [Platform APIs](https://github.com/dotnet/macios/tree/main/src): `src`
- [Foundation types](https://github.com/dotnet/macios/tree/main/src/Foundation): `src/Foundation`
- [UI frameworks](https://github.com/dotnet/macios/tree/main/src/UIKit): `src/UIKit`
- [Media frameworks](https://github.com/dotnet/macios/tree/main/src/AVFoundation): `src/AVFoundation`
- [Apple frameworks](https://github.com/dotnet/macios/tree/main/src): `src`
- [Binding generator](https://github.com/dotnet/macios/blob/main/src/bgen/Generator.cs): `src/bgen/Generator.cs`
- [Binding attributes](https://github.com/dotnet/macios/blob/main/src/bgen/AttributeManager.cs): `src/bgen/AttributeManager.cs`
- [Rgen model](https://github.com/dotnet/macios/blob/main/src/rgen/Microsoft.Macios.Generator/DataModel/Constructor.cs): `src/rgen/Microsoft.Macios.Generator/DataModel/Constructor.cs`

### Managed runtime

- [Objective-C runtime](https://github.com/dotnet/macios/blob/main/src/ObjCRuntime/Runtime.cs): `src/ObjCRuntime/Runtime.cs`
- [Native handles](https://github.com/dotnet/macios/blob/main/src/ObjCRuntime/NativeHandle.cs): `src/ObjCRuntime/NativeHandle.cs`
- [Runtime errors](https://github.com/dotnet/macios/blob/main/src/ObjCRuntime/ThrowHelper.cs): `src/ObjCRuntime/ThrowHelper.cs`
- [HTTP transport](https://github.com/dotnet/macios/blob/main/src/Foundation/NSUrlSessionHandler.cs): `src/Foundation/NSUrlSessionHandler.cs`

### Build integration

- [Apple build tasks](https://github.com/dotnet/macios/tree/main/msbuild/Xamarin.MacDev.Tasks/Tasks): `msbuild/Xamarin.MacDev.Tasks/Tasks`
- [Build messaging](https://github.com/dotnet/macios/blob/main/msbuild/Messaging/Xamarin.Messaging.Build/BuildEngine.cs): `msbuild/Messaging/Xamarin.Messaging.Build/BuildEngine.cs`

### Other components

- **App developer**
- **Apple frameworks**

## Connections

- App developer → App templates: starts from
- App developer → Platform APIs: uses APIs (evidence: `README.md`)
- App templates → Platform APIs: scaffolds apps
- Platform APIs → Foundation types: uses types (evidence: `src/AVKit/AVPlayerViewController.cs`)
- Platform APIs → UI frameworks: includes UI (evidence: `src/browserenginekit.cs`)
- Platform APIs → Media frameworks: includes media (evidence: `src/browserenginecore.cs`)
- Platform APIs → Apple frameworks: includes services
- Binding generator → Binding attributes: reads attributes (evidence: `src/bgen/AttributeManager.cs`)
- Binding generator → Platform APIs: generates bindings (evidence: `src/bgen/AttributeManager.cs`)
- Rgen model → Platform APIs: models bindings (evidence: `src/rgen/Microsoft.Macios.Generator/DataModel/Constructor.cs`)
- Platform APIs → Objective-C runtime: bridges calls (evidence: `src/Security/AuthorizationEngine.cs`)
- Objective-C runtime → Native handles: constructs wrappers (evidence: `src/ObjCRuntime/Runtime.cs`)
- Objective-C runtime → Runtime errors: raises errors (evidence: `src/ObjCRuntime/ThrowHelper.cs`)
- Foundation types → HTTP transport: provides transport (evidence: `src/Foundation/NSUrlSessionHandler.cs`)
- HTTP transport → Apple frameworks: sends requests
- Apple build tasks → Build messaging: uses messaging
