# grpc/grpc-java architecture

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

## Overview

##### Project type and purpose
- This is a multi-module monorepo hosting gRPC-Java: a Java RPC library and framework.
- Its purpose is to provide a layered RPC stack (Stub → Channel → Transport), plus plugins, sample apps, tests, and build tooling.

##### File structure
- Top-level build files (.bazel, build.gradle, WORKSPACE) show support for Bazel and Gradle.
- There are dozens of subdirectories each built as an independent module:
- api, stub – the public API and generated client/server stubs
- core – channel logic (load balancing, name resolution, interceptors)
- transport modules – netty, okhttp, inprocess, binder, cronet, xds, s2a, alts, rls, grpclb, etc.
- extensions – auth, authz, census, gcp-observability
- services – channelz, health, reflection
- tools – compiler plugin, examples, benchmarks, testing harnesses, buildSrc, buildscripts
- Each module has its own src/main/java, src/test/java, proto directories for codegen.

##### README for additional insights
- The README defines three high-level layers: Stub, Channel, Transport.
- It lists supported transports (Netty, OkHttp, In-Process, Binder) and discusses codegen via the compiler plugin.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External
    APP["Application Code"]:::external

    %% Stub Layer
    subgraph "Stub Layer"
        stub_api["Public API"]:::api
        stub_gen["Generated Stubs"]:::api
    end

    %% Channel Layer
    subgraph "Channel Layer"
        core["Core Channel"]:::core
    end

    %% Extensions & Utilities
    subgraph "Extensions & Utilities"
        auth["Auth"]:::extension
        authz["AuthZ"]:::extension
        census["Census"]:::extension
        csm["GCP CSM Obs"]:::extension
        obs["GCP Obs"]:::extension
        util["Utilities"]:::extension
    end

    %% Transport Layer
    subgraph "Transport Layer"
        netty["Netty"]:::transport
        okhttp["OkHttp"]:::transport
        inproc["InProc"]:::transport
        binder["Binder"]:::transport
        cronet["Cronet"]:::transport
        xds["xDS"]:::transport
        s2a["S2A"]:::transport
        alts["ALTS"]:::transport
        rls["RLS"]:::transport
        grpclb["GRPCLB"]:::transport
    end

    %% Services Layer
    subgraph "Services Layer"
        services["Channelz/Health/Reflection"]:::extension
    end

    %% Tools & Build
    subgraph "Tools & Build"
        compiler["Codegen Plugin"]:::tools
        examples["Examples"]:::tools
        benchmarks["Benchmarks"]:::tools
        testing["Testing Harness"]:::tools
        interop["Interop Tests"]:::tools
        androidInterop["Android Interop"]:::tools
        gae["GAE Interop"]:::tools
        istio["Istio Interop"]:::tools
        buildsrc["BuildSrc"]:::tools
        buildscripts["BuildScripts"]:::tools
    end

    %% Connections
    APP -->|"RPC call"| stub_api
    stub_api --> stub_gen
    stub_gen -->|"ManagedChannel API"| core
    core --> util
    core --> auth
    core --> authz
    core --> census
    core --> csm
    core --> obs
    core --> netty
    core --> okhttp
    core --> inproc
    core --> binder
    core --> cronet
    core --> xds
    core --> s2a
    core --> alts
    core --> rls
    core --> grpclb
    core --> services
    compiler --> stub_gen

    %% Click Events
    click stub_api "https://github.com/grpc/grpc-java/tree/master/api/"
    click stub_gen "https://github.com/grpc/grpc-java/tree/master/stub/"
    click core "https://github.com/grpc/grpc-java/tree/master/core/"
    click auth "https://github.com/grpc/grpc-java/tree/master/auth/"
    click authz "https://github.com/grpc/grpc-java/tree/master/authz/"
    click census "https://github.com/grpc/grpc-java/tree/master/census/"
    click csm "https://github.com/grpc/grpc-java/tree/master/gcp-csm-observability/"
    click obs "https://github.com/grpc/grpc-java/tree/master/gcp-observability/"
    click util "https://github.com/grpc/grpc-java/tree/master/util/"
    click netty "https://github.com/grpc/grpc-java/tree/master/netty/"
    click okhttp "https://github.com/grpc/grpc-java/tree/master/okhttp/"
    click inproc "https://github.com/grpc/grpc-java/tree/master/inprocess/"
    click binder "https://github.com/grpc/grpc-java/tree/master/binder/"
    click cronet "https://github.com/grpc/grpc-java/tree/master/cronet/"
    click xds "https://github.com/grpc/grpc-java/tree/master/xds/"
    click s2a "https://github.com/grpc/grpc-java/tree/master/s2a/"
    click alts "https://github.com/grpc/grpc-java/tree/master/alts/"
    click rls "https://github.com/grpc/grpc-java/tree/master/rls/"
    click grpclb "https://github.com/grpc/grpc-java/tree/master/grpclb/"
    click services "https://github.com/grpc/grpc-java/tree/master/services/"
    click compiler "https://github.com/grpc/grpc-java/tree/master/compiler/"
    click examples "https://github.com/grpc/grpc-java/tree/master/examples/"
    click benchmarks "https://github.com/grpc/grpc-java/tree/master/benchmarks/"
    click testing "https://github.com/grpc/grpc-java/tree/master/testing/"
    click interop "https://github.com/grpc/grpc-java/tree/master/interop-testing/"
    click androidInterop "https://github.com/grpc/grpc-java/tree/master/android-interop-testing/"
    click gae "https://github.com/grpc/grpc-java/tree/master/gae-interop-testing/"
    click istio "https://github.com/grpc/grpc-java/tree/master/istio-interop-testing/"
    click buildsrc "https://github.com/grpc/grpc-java/tree/master/buildSrc/"
    click buildscripts "https://github.com/grpc/grpc-java/tree/master/buildscripts/"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#1B4F72,color:#154360
    classDef core fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef transport fill:#FDEDEC,stroke:#C0392B,color:#78281F
    classDef extension fill:#F2F3F4,stroke:#7B7D7D,color:#424949
    classDef tools fill:#EBDEF0,stroke:#7D3C98,color:#512E5F
    classDef external fill:#F9E79F,stroke:#B7950B,color:#7D6608
```
