# grpc/grpc-swift-2 architecture

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

## Overview

##### Project Type and Purpose
- This is an open-source gRPC implementation in Swift. It provides:
- A **protoc plugin** (GRPCCodeGen) that generates Swift stubs from .proto files
- A **runtime library** (GRPCCore) implementing client/server call handling, streaming, codecs, configuration
- An **in-process transport** (GRPCInProcessTransport) for local testing
- A **CLI dev tool** (grpc-dev-tool) for developers
- **Examples**, **integration tests**, and **benchmarks** illustrating usage

##### High-Level File Structure Analysis
- **Sources/GRPCCodeGen**: protoc plugin
- Translator → StructuredSwiftRepresentation → Renderer → Swift source files
- **Sources/GRPCCore**: runtime layers
- Call (Client / Server executors, interceptors)
- Coding (compression, byte-buffer mapping)
- Configuration (method/service configs)
- Streaming (async sequences, RPCWriter)
- Transport (abstract ClientTransport / ServerTransport)
- **Sources/GRPCInProcessTransport**: in-memory transport conforming to Transport protocols
- **dev/grpc-dev-tool**: CLI with subcommands (e.g., GenerateJSON)
- **Examples**: sample Swift packages illustrating server/client code generation & runtime usage
- **Tests / IntegrationTests**: unit, end-to-end, benchmarks
- **Docs**: markdown + DocC tutorials

##### Key Components
a. **Protoc & Code Generation**
- .proto files → protoc → GRPCCodeGen plugin → Generated Swift stubs
b. **Runtime Library (GRPCCore)**
- **Call Layer**: ClientRequest/Response, ServerRequest/Response, RPC executors, interceptors
- **Coding Layer**: serializers, compression algorithms, byte buffers
- **Configuration**: MethodConfig, ServiceConfig parsers
- **Streaming**: RPCWriter, AsyncSequence wrappers
- **Transport Abstraction**: ClientTransport / ServerTransport interfaces
c. **Transports**
- **GRPCNIOTransportHTTP2** (external dependency)
- **GRPCInProcessTransport** (built-in in-process transport)
d. **CLI Dev Tool**
- grpc-dev-tool with GenerateJSON, other subcommands
e. **Examples & Tests**
- Plugin+runtime usage; wire into real / in-process transports
f. **External Dependencies**
- SwiftProtobuf (message serialization)
- SwiftNIO (I/O event loop for HTTP/2 transport)

##### Relationships & Interactions
- **Data Flow**:
1. Developer writes .proto → runs protoc with GRPCCodeGen
2. Plugin emits Swift client/server stubs
3. Application imports GRPCCore + chosen transport (e.g., GRPCNIOTransportHTTP2) + SwiftProtobuf
4. App calls generated client stubs → GRPCCore.Call → Coding → Transport → Network or In-Process
5. Server: GRPCCore.Server → user-provided service implementation → transport → stream → client
- **Layering**: CodeGen is separate from runtime. Runtime is layered Call → Coding → Transport.

##### Architectural Patterns & Design Principles
- **Layered Architecture**: clear separation between generation, runtime layers, transports
- **Dependency Inversion**: transport is protocol-based, runtime doesn’t depend on concrete HTTP/2
- **Extensibility**: CodeGen translators & renderers, multi-transport support, interceptors
- **Modularity**: each submodule (CodeGen, Core, InProcessTransport, Dev Tool) in its own target

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Protocol Definitions
    ProtoFiles[(.proto files)]:::artifact
    Protoc["protoc"]:::process

    %% Code Generation Plugin
    subgraph "GRPCCodeGen Plugin" 
        direction TB
        Translator["Translator"]:::codegen
        SSR["StructuredSwiftRepresentation"]:::codegen
        Renderer["Renderer (TextBasedRenderer & RendererProtocol)"]:::codegen
    end

    GeneratedStubs[(Generated Swift stubs)]:::artifact

    %% Runtime Core Library
    subgraph "GRPCCore Runtime" 
        direction TB
        subgraph "Call Layer"
            direction TB
            Client["ClientRequest/Response & Interceptors"]:::runtime
            Server["ServerRequest/Response & Interceptors"]:::runtime
            ConditionalInterceptor["ConditionalInterceptor"]:::runtime
        end
        subgraph "Coding Layer"
            direction TB
            Coding["Serializers & Compression"]:::runtime
        end
        subgraph "Configuration"
            direction TB
            Config["MethodConfig & ServiceConfig"]:::runtime
        end
        subgraph "Streaming"
            direction TB
            Streaming["RPCWriter & AsyncSequence"]:::runtime
        end
        subgraph "Transport Abstraction"
            direction TB
            TransportAPI["ClientTransport & ServerTransport"]:::runtime
        end
        APIEntrypoints["GRPCClient & GRPCServer"]:::runtime
    end

    %% Transports
    subgraph "Transports"
        direction TB
        HTTP2["GRPCNIOTransportHTTP2"]:::external
        InProcess["GRPCInProcessTransport"]:::transport
    end

    %% CLI Dev Tool
    DevTool["grpc-dev-tool CLI"]:::cli
    subgraph "GenerateJSON Subcommand"
        direction TB
        JSONGen["GenerateJSON"]:::cli
    end

    %% Examples and Tests
    subgraph "Examples & Tests"
        direction TB
        Examples["Examples (echo, hello-world, etc.)"]:::example
        IntegrationTests["IntegrationTests & Benchmarks"]:::test
        UnitTests["Unit Tests"]:::test
    end

    %% External Dependencies
    SwiftProtobuf["SwiftProtobuf"]:::external
    SwiftNIO["SwiftNIO"]:::external

    %% Data Flows
    ProtoFiles -->|"input to"| Protoc
    Protoc -->|"invokes plugin"| Translator
    Translator --> SSR
    SSR --> Renderer
    Renderer -->|"generates"| GeneratedStubs

    GeneratedStubs -->|"import into"| APIEntrypoints
    APIEntrypoints --> Client
    APIEntrypoints --> Server
    Client --> Coding
    Server --> Coding
    Coding --> TransportAPI
    TransportAPI --> HTTP2
    TransportAPI --> InProcess
    Client --> SwiftProtobuf
    Server --> SwiftProtobuf
    HTTP2 --> SwiftNIO

    DevTool --> JSONGen
    JSONGen --> Translator

    Examples --> GeneratedStubs
    Examples --> APIEntrypoints
    Examples --> InProcess

    IntegrationTests --> InProcess
    IntegrationTests --> HTTP2

    UnitTests --> Translator
    UnitTests --> APIEntrypoints
    UnitTests --> InProcess

    %% Click Events
    click Translator "https://github.com/grpc/grpc-swift-2/tree/main/Sources/GRPCCodeGen/Internal/Translator"
    click SSR "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCodeGen/Internal/StructuredSwiftRepresentation.swift"
    click Renderer "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCodeGen/Internal/Renderer/TextBasedRenderer.swift"
    click Renderer "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCodeGen/Internal/Renderer/RendererProtocol.swift"
    click Client "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCore/Call/Client/ClientRequest.swift"
    click Server "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCore/Call/Server/ServerRequest.swift"
    click ConditionalInterceptor "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCore/Call/ConditionalInterceptor.swift"
    click Coding "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCore/Coding/Coding.swift"
    click Config "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCore/Configuration/MethodConfig.swift"
    click Streaming "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCore/Streaming/RPCWriter.swift"
    click TransportAPI "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCore/Transport/ClientTransport.swift"
    click APIEntrypoints "https://github.com/grpc/grpc-swift-2/blob/main/Sources/GRPCCore/GRPCClient.swift"
    click InProcess "https://github.com/grpc/grpc-swift-2/tree/main/Sources/GRPCInProcessTransport"
    click DevTool "https://github.com/grpc/grpc-swift-2/blob/main/dev/grpc-dev-tool/Sources/grpc-dev-tool/GRPCDevTool.swift"
    click JSONGen "https://github.com/grpc/grpc-swift-2/blob/main/dev/grpc-dev-tool/Sources/grpc-dev-tool/Subcommands/GenerateJSON/JSONCodeGenerator.swift"

    %% Styles
    classDef codegen fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef runtime fill:#E6FFEA,stroke:#28A745,color:#28A745;
    classDef transport fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef process fill:#FFF5B1,stroke:#DBAB09,color:#735C0F;
    classDef artifact fill:#E0F7FA,stroke:#00796B,color:#00796B;
    classDef cli fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A;
    classDef example fill:#FFF0F6,stroke:#D6336C,color:#A61E4D;
    classDef test fill:#F5F5F5,stroke:#636363,color:#24292E;
```
