# grpc/grpc-ios architecture

> Architecture diagram of the GitHub repository grpc/grpc-ios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grpc/grpc-ios
- Repository: https://github.com/grpc/grpc-ios

## Overview

##### Project Type & Purpose
- This is an open-source, multi-language RPC framework. At its heart is a C++ core library (“src/core”) implementing RPC logic (transport, call lifecycle, credentials, load-balancing, etc.). On top of this core sit language-specific client/server APIs (C++, Objective-C, Python, Ruby, PHP, C#, etc.). Tools, scripts, and CI integrate and package the libraries for various ecosystems.

##### Logical Components
a. Core C++ Library (src/core)
- Subsystems:
– Call handling (call spine, filters, message batching)
– Transport (HTTP/2, in-proc, channel stacks)
– Credentials & security (TLS, ALTS, token fetchers)
– Resolver & naming (DNS, xDS, polling)
– Load balancing (grpclb, round robin, pick-first, xDS)
– Service config & filters (fault injection, auth, census)
– Surface API (public C API, channel and call factories)
- Extensions & plugins: gRPC plugins, upb codegen, third-party libs (re2, zlib, upb).
b. Language Bindings & Wrappers
- C++ Wrapper (“src/cpp”): idiomatic C++ class interfaces (CompletionQueue, Stub, ServerBuilder) built atop core C API.
- Objective-C (src/objective-c), Python (src/python), Ruby (src/ruby), PHP (src/php), C# (src/csharp), etc.: each defines a thin layer calling into the core library.
c. Public Headers & Packaging
- “include/” and “spm-*-include/”: publicly exposed headers for CocoaPods, SwiftPM, and other package managers.
- Podspecs, Package.swift, scripts/: build and package for SPM, CocoaPods, NuGet, pip, gem.
d. CI & Release Automation
- .github/workflows: sync sources, lint, tests, publish to package registries.
- scripts/: pre-submit checks, build sample apps, publish pods, handle versioning.
e. Tests & Samples
- tests/spm, tests/cocoapod: sample applications demonstrating usage.
- end-to-end and unit tests in each language directory.

##### Relationships & Data Flow
- Language API → links against → Core C++ Library → uses → Third-Party Dependencies (upb, re2, zlib)
- Core Library interacts with system/network via Transport & I/O (posix, event engine).
- Resolver subsystem queries DNS/xDS to discover endpoints.
- Load Balancer picks subchannels for RPC; filters apply logging, metrics, auth.
- Service config directs behavior (timeouts, retry, fault inject).
- CI workflows invoke scripts, which call build tools and generate language packages.

##### Architectural Patterns & Principles
- Modular layering: core engine separated from language surface.
- Plugin/extension-based filters and transport.
- Factory patterns for channels, resolvers, credentials.
- Asynchronous event‐driven model (CompletionQueue).
- Code-generation (upb, protobuf) for APIs and xDS.

##### Essential Elements
- Modules grouped by functionality (transport, security, resolver, load balancing, surface API).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Language Bindings Layer
    subgraph "Language Bindings"
        direction TB
        Cpp["C++ Binding"]:::lang
        ObjC["Objective-C Binding"]:::lang
        Python["Python Binding"]:::lang
        Ruby["Ruby Binding"]:::lang
        PHP["PHP Binding"]:::lang
        CSharp["C# Binding"]:::lang
    end

    %% Core Library
    subgraph "Core C++ Library" 
        direction TB
        Call["Call Handling"]:::core
        Transport["Transport"]:::core
        Creds["Credentials & Security"]:::core
        Resolver["Resolver & Naming"]:::core
        LB["Load Balancing"]:::core
        SC["Service Config & Filters"]:::core
        Surface["Surface API"]:::core
    end

    %% Plugin & Codegen
    subgraph "Plugin & Codegen"
        direction TB
        UpbPlugin["UPB Plugins"]:::core
        UpbDefs["UPBDefs Plugins"]:::core
    end

    %% Third-Party Dependencies
    subgraph "Third-Party Dependencies"
        direction TB
        RE2["re2"]:::ext
        Zlib["zlib"]:::ext
        UPB["upb"]:::ext
    end

    %% Public Headers & Packaging
    subgraph "Public Headers & Packaging"
        direction TB
        Headers["include/, spm-*-include/"]:::infra
        Specs["Podspecs & Package.swift"]:::infra
    end

    %% CI & Release Automation
    subgraph "CI & Release Automation"
        direction TB
        Workflows[".github/workflows"]:::infra
        Scripts["scripts/"]:::infra
    end

    %% Samples & Tests
    subgraph "Samples & Tests"
        direction TB
        Cocoa["tests/cocoapod"]:::infra
        SPM["tests/spm"]:::infra
    end

    %% Connections: Language Bindings -> Core
    Cpp -->|"links against"| Surface
    ObjC -->|"links against"| Surface
    Python -->|"links against"| Surface
    Ruby -->|"links against"| Surface
    PHP -->|"links against"| Surface
    CSharp -->|"links against"| Surface

    %% Core internal dependencies
    Surface -->|"uses"| Call
    Surface -->|"uses"| Transport
    Surface -->|"uses"| Creds
    Surface -->|"uses"| Resolver
    Surface -->|"uses"| LB
    Surface -->|"uses"| SC
    Call -->|"uses filters"| SC
    Transport -->|"pluggable"| UpbPlugin
    Transport -->|"protocols"| UpbDefs

    %% Core -> Third-Party
    Call -->|"uses"| UPB
    Transport -->|"uses"| Zlib
    Creds -->|"uses"| RE2

    %% Packaging & CI
    Workflows -->|"invoke"| Scripts
    Scripts -->|"build & package"| Specs
    Scripts -->|"copy headers"| Headers
    Scripts -->|"generate samples"| Cocoa
    Scripts -->|"generate samples"| SPM
    Workflows -->|"publish to registry"| Specs

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef lang fill:#E6FFED,stroke:#22863A,stroke-width:1px
    classDef ext fill:#FFF5B1,stroke:#E36209,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#6A737D,stroke-width:1px

    %% Click Events
    click Call "https://github.com/grpc/grpc-ios/tree/main/src/core/call"
    click Transport "https://github.com/grpc/grpc-ios/tree/main/src/core/ext/transport"
    click Transport "https://github.com/grpc/grpc-ios/tree/main/src/core/lib/transport"
    click Creds "https://github.com/grpc/grpc-ios/tree/main/src/core/credentials"
    click Creds "https://github.com/grpc/grpc-ios/tree/main/src/core/tsi"
    click Resolver "https://github.com/grpc/grpc-ios/tree/main/src/core/resolver"
    click LB "https://github.com/grpc/grpc-ios/tree/main/src/core/load_balancing"
    click SC "https://github.com/grpc/grpc-ios/tree/main/src/core/service_config"
    click SC "https://github.com/grpc/grpc-ios/tree/main/src/core/ext/filters"
    click Surface "https://github.com/grpc/grpc-ios/tree/main/src/core/lib/surface"
    click UpbPlugin "https://github.com/grpc/grpc-ios/tree/main/src/core/ext/upb-gen"
    click UpbDefs "https://github.com/grpc/grpc-ios/tree/main/src/core/ext/upbdefs-gen"
    click RE2 "https://github.com/grpc/grpc-ios/tree/main/third_party/re2"
    click Zlib "https://github.com/grpc/grpc-ios/tree/main/third_party/zlib"
    click UPB "https://github.com/grpc/grpc-ios/tree/main/third_party/upb"
    click Cpp "https://github.com/grpc/grpc-ios/tree/main/src/cpp"
    click ObjC "https://github.com/grpc/grpc-ios/tree/main/src/objective-c"
    click Python "https://github.com/grpc/grpc-ios/tree/main/src/python"
    click Ruby "https://github.com/grpc/grpc-ios/tree/main/src/ruby"
    click PHP "https://github.com/grpc/grpc-ios/tree/main/src/php"
    click CSharp "https://github.com/grpc/grpc-ios/tree/main/src/csharp"
    click Headers "https://github.com/grpc/grpc-ios/tree/main/include/"
    click Headers "https://github.com/grpc/grpc-ios/tree/main/spm-core-include/"
    click Headers "https://github.com/grpc/grpc-ios/tree/main/spm-cpp-include/"
    click Specs "https://github.com/grpc/grpc-ios/blob/main/gRPC-*.podspec"
    click Specs "https://github.com/grpc/grpc-ios/blob/main/Package.swift"
    click Scripts "https://github.com/grpc/grpc-ios/tree/main/scripts/"
    click Workflows "https://github.com/grpc/grpc-ios/tree/main/.github/workflows/"
    click Cocoa "https://github.com/grpc/grpc-ios/tree/main/tests/cocoapod"
    click SPM "https://github.com/grpc/grpc-ios/tree/main/tests/spm"
```
