# grpc/grpc-web architecture

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

## Overview

##### Project type and purpose
- This is an open-source library and code-generation tool (“grpc-web”) that lets browser clients use gRPC services.
- It contains two core deliverables:
- A runtime JavaScript/TypeScript client library (in javascript/net/grpc/web and packages/grpc-web)
- A protoc plugin (in javascript/net/grpc/web/generator) to generate JS/TS gRPC stubs from .proto files
- It also bundles examples (net/grpc/gateway/examples), tests, a Docker-Compose demo, and build scripts (Makefile, Bazel, scripts/).

##### File structure
- Top-level directories:
- javascript/net/grpc/web → runtime client code (JS/TS interfaces, transport, interceptors)
- javascript/net/grpc/web/generator → code generator source (C++/Zig + Bazel)
- packages/grpc-web → npm packaging, test harness, build scripts
- net/grpc/gateway/examples → demo services (Node.js server), Envoy configs, client web apps
- scripts/, docker-compose.yml → CI, build/test orchestration
- src/proto, test/interop → shared proto definitions and interop tests
- Build tools: Bazel (MODULE.bazel), Docker (docker-compose.yml, .dockerignore), npm/Gulp (packages/grpc-web).

##### README for insights
- Describes a typical workflow:
1. Service in .proto
2. Run protoc + protoc-gen-js + protoc-gen-grpc-web → generates *_pb.js + *_grpc_web_pb.js (+ .d.ts)
3. Bundle with Webpack/Browserify/Closure → browser app
4. Browser calls gRPC-Web → Envoy proxy → real gRPC server
- Highlights architecture: client library, proxy (Envoy or alternative), server frameworks.

- From developer tools → generated stubs → bundler → browser
- From browser → proxy → backend → proxy → browser
- Tools/Build (gray gears)
- Codegen plugins (blue hexagons)

##### Detail
- Every stage: .proto definitions, plugins, bundler, client runtime, network hops, server
- Don’t omit the test/CI flows or packaging steps for npm/Bazel
- That the generator is itself built by Bazel and packaged alongside the runtime

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Developer Environment"
        PROTO[".proto Definitions"]:::tools
        PROTO --> PROTOC["protoc"]:::tools
        subgraph "Code Generation Plugins"
            PGJS["protoc-gen-js"]:::plugin
            PGGW["protoc-gen-grpc-web"]:::plugin
        end
        PROTOC --> PGJS
        PROTOC --> PGGW
        PGJS --> STUBS["Generated JS/TS Stubs"]:::tools
        PGGW --> STUBS
    end

    subgraph "Build & Packaging"
        BAZEL["MODULE.bazel"]:::tools
        MAKEFILE["Makefile"]:::tools
        SCRIPTS["scripts/"]:::tools
        NPM["npm Packaging & Test Harness"]:::tools
        WEBPACK["Bundler (Webpack/Gulp)"]:::tools
        STUBS --> WEBPACK
        WEBPACK --> BUNDLE["Client Bundle"]:::tools
        BUNDLE --> RUNTIME["Runtime Library"]:::runtime
    end

    subgraph "Client Application"
        EXAMPLES["Demo Client Apps & Services"]:::examples
        BUNDLE --> EXAMPLES
        EXAMPLES --> BROWSER["Browser App"]:::client
    end

    subgraph "Network Flow"
        BROWSER --> PROXY["Envoy Proxy"]:::infra
        PROXY --> GRPC["Backend gRPC Server"]:::infra
        GRPC --> PROXY
        PROXY --> BROWSER
    end

    subgraph "Docker & Proxy"
        DOCKERCOMPOSE["docker-compose.yml"]:::infra
        DOCKERCOMPOSE --> PROXY
    end

    subgraph "CI / Test Harness"
        DOCKERCOMPOSECI["docker-compose.yml"]:::infra
        INTEROP["Interop Test Suite"]:::examples
        GH[".github/workflows"]:::tools
        KOKORO["kokoro"]:::tools
        DOCKERCOMPOSECI --> INTEROP
        DOCKERCOMPOSECI --> MAKEFILE
        DOCKERCOMPOSECI --> SCRIPTS
        DOCKERCOMPOSECI --> GH
        DOCKERCOMPOSECI --> KOKORO
    end

    classDef tools fill:#e0e0e0,stroke:#000;
    classDef plugin fill:#aed6f1,stroke:#000;
    classDef runtime fill:#a9dfbf,stroke:#000;
    classDef infra fill:#f5b7b1,stroke:#000;
    classDef examples fill:#f4ecf7,stroke:#8e44ad,stroke-dasharray: 5 5;
    classDef client fill:#d5f5e3,stroke:#27ae60;

    click RUNTIME "https://github.com/grpc/grpc-web/tree/master/javascript/net/grpc/web"
    click PGGW "https://github.com/grpc/grpc-web/tree/master/javascript/net/grpc/web/generator"
    click NPM "https://github.com/grpc/grpc-web/tree/master/packages/grpc-web"
    click EXAMPLES "https://github.com/grpc/grpc-web/tree/master/net/grpc/gateway/examples"
    click DOCKERCOMPOSE "https://github.com/grpc/grpc-web/blob/master/docker-compose.yml"
    click PROXY "https://github.com/grpc/grpc-web/tree/master/net/grpc/gateway/docker"
    click PROTO "https://github.com/grpc/grpc-web/tree/master/src/proto"
    click INTEROP "https://github.com/grpc/grpc-web/tree/master/test/interop"
    click MAKEFILE "https://github.com/grpc/grpc-web/tree/master/Makefile"
    click SCRIPTS "https://github.com/grpc/grpc-web/tree/master/scripts/"
    click BAZEL "https://github.com/grpc/grpc-web/blob/master/MODULE.bazel"
    click GH "https://github.com/grpc/grpc-web/tree/master/.github/workflows"
    click KOKORO "https://github.com/grpc/grpc-web/tree/master/kokoro"
```
