# grpc/grpc-swift-protobuf architecture

> Architecture diagram of the GitHub repository grpc/grpc-swift-protobuf, 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-swift-protobuf
- Repository: https://github.com/grpc/grpc-swift-protobuf

## Overview

##### Project type and purpose
- This is an open-source Swift Package that integrates with SwiftProtobuf to generate gRPC client and server stubs in Swift. It provides:
- A C library (CGRPCProtobuf) for low-level protobuf encoding/decoding and bridging to Swift.
- A Swift runtime library (GRPCProtobuf) implementing high-level gRPC functionality.
- A code‐generation plugin (protoc-gen-grpc-swift‐2) that reads `.proto` files and emits Swift sources.
- Swift Package Manager build plugins (`GRPCProtobufGenerator`, `GRPCProtobufGeneratorCommand`) to wire codegen into SPM builds or CLI workflows.

##### File structure
- Top-level directories:
- `Sources/`
– `CGRPCProtobuf`: C runtime + headers
– `GRPCProtobuf`: Swift runtime + docs + error types
– `GRPCProtobufCodeGen`: core code-generation logic (parser + generator)
– `protoc-gen-grpc-swift-2`: the entry point for the gRPC Swift protoc plugin
- `Plugins/`
– `GRPCProtobufGenerator`: SPM build‐plugin implementation (BuildPlugin API)
– `GRPCProtobufGeneratorCommand`: CLI wrapper around the plugin logic
– `PluginsShared`: common utilities and config types
- `Tests/`: unit tests for code gen and runtime
- `IntegrationTests/`: sample `.proto` input + expected generated code + SPM test harness
- `dev/`: scripts for CI, code formatting, protos fetching, versioning
- Configuration and CI: `.github/workflows/`, `Package.swift`, various lint/config files.

##### Key insights from the README
- Purpose: “integrations with SwiftProtobuf for gRPC Swift”
- Targets: SPM users; integrates as a plugin for `protoc` and as an SPM build plugin.
- Documentation points to external Swift Package Index resources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Code Generation Pipeline
    subgraph "Code Generation Pipeline"
        direction TB
        ProtoFiles[".proto files"]:::codegen
        Protoc["protoc"]:::codegen
        PluginEntry["protoc-gen-grpc-swift-2"]:::codegen
        CoreLib["GRPCProtobufCodeGen"]:::codegen
        Parser["ProtobufCodeGenParser"]:::codegen
        Generator["ProtobufCodeGenerator"]:::codegen
        GeneratedFiles["Generated Swift Stubs"]:::codegen
    end

    %% Runtime Libraries
    subgraph "Runtime Libraries"
        direction TB
        CRuntime["CGRPCProtobuf (C Library)"]:::runtime
        SwiftRuntime["GRPCProtobuf (Swift Runtime)"]:::runtime
    end

    %% SPM and CLI Plugins
    subgraph "SPM Plugins & CLI"
        direction TB
        SPMPlugin["GRPCProtobufGenerator\n(Build Plugin)"]:::plugin
        CLIPlugin["GRPCProtobufGeneratorCommand\n(CLI Wrapper)"]:::plugin
        SharedUtils["PluginsShared"]:::plugin
    end

    %% Tests
    subgraph "Tests"
        direction TB
        UnitCodeGen["CodeGen Unit Tests"]:::tests
        UnitRuntime["Runtime Unit Tests"]:::tests
        Integration["IntegrationTests"]:::tests
    end

    %% Consumer
    App["Consumer App / Tests"]:::other

    %% Connections
    ProtoFiles --> Protoc
    Protoc -->|"--plugin=protoc-gen-grpc-swift-2"| PluginEntry
    PluginEntry -->|"uses"| CoreLib
    CoreLib --> Parser
    Parser --> Generator
    Generator --> GeneratedFiles
    GeneratedFiles -->|"compile & link"| SwiftRuntime
    SwiftRuntime --> CRuntime

    SPMPlugin -->|"invokes protoc"| Protoc
    CLIPlugin -->|"invokes protoc"| Protoc
    SPMPlugin --> SharedUtils
    CLIPlugin --> SharedUtils

    App --> GeneratedFiles
    App --> SwiftRuntime
    Integration --> SPMPlugin
    Integration --> GeneratedFiles
    UnitCodeGen --> CoreLib
    UnitRuntime --> SwiftRuntime

    %% Click Events
    click CRuntime "https://github.com/grpc/grpc-swift-protobuf/tree/main/Sources/CGRPCProtobuf"
    click SwiftRuntime "https://github.com/grpc/grpc-swift-protobuf/tree/main/Sources/GRPCProtobuf"
    click CoreLib "https://github.com/grpc/grpc-swift-protobuf/tree/main/Sources/GRPCProtobufCodeGen"
    click PluginEntry "https://github.com/grpc/grpc-swift-protobuf/tree/main/Sources/protoc-gen-grpc-swift-2"
    click SPMPlugin "https://github.com/grpc/grpc-swift-protobuf/tree/main/Plugins/GRPCProtobufGenerator"
    click CLIPlugin "https://github.com/grpc/grpc-swift-protobuf/tree/main/Plugins/GRPCProtobufGeneratorCommand"
    click SharedUtils "https://github.com/grpc/grpc-swift-protobuf/tree/main/Plugins/PluginsShared"
    click UnitCodeGen "https://github.com/grpc/grpc-swift-protobuf/tree/main/Tests/GRPCProtobufCodeGenTests"
    click UnitRuntime "https://github.com/grpc/grpc-swift-protobuf/tree/main/Tests/GRPCProtobufTests"
    click Integration "https://github.com/grpc/grpc-swift-protobuf/tree/main/IntegrationTests/PluginTests"

    %% Styles
    classDef codegen fill:#D0E8FF,stroke:#0066CC,color:#003366
    classDef runtime fill:#D0FFD8,stroke:#339933,color:#003300
    classDef plugin fill:#FFE8D0,stroke:#CC6600,color:#663300
    classDef tests fill:#F0F0F0,stroke:#999999,color:#333333
    classDef other fill:#FFD8D8,stroke:#CC3333,color:#660000
```
