# grpc-ecosystem/grpc-gateway architecture

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

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

## Overview

##### Main Components

a) Core Components:
- Protocol Buffer Compiler Plugins
- protoc-gen-grpc-gateway (Gateway Generator)
- protoc-gen-openapiv2 (OpenAPI/Swagger Generator)
- Runtime Package
- Generated Reverse Proxy Server
- gRPC Server
- HTTP/JSON Clients

b) Supporting Components:
- Internal Libraries
- Descriptor handling
- HTTP rule parsing
- Code generation utilities
- Configuration Systems
- Annotations
- External API configurations

##### Flow Representations

- HTTP → Gateway → gRPC
- gRPC → Gateway → HTTP
- Proto Files → Plugins → Generated Code
- Annotations → Generator
- External Config → Generator

##### Specific Elements to Highlight

a) Protocol Transformation:
- HTTP request transformation to gRPC
- GRPC response transformation to HTTP/JSON
- Metadata/header mapping

b) Generation Process:
- Proto file input
- Annotation processing
- Generated code output
- OpenAPI specification generation

##### Important Details

Annotations for:
- Port numbers (default 8081 for HTTP, 9090 for gRPC)
- Supported protocols (HTTP 1.1, HTTP/2)
- Key configuration options
- File formats (.proto, .yaml, .json)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        HTTP["HTTP/JSON Clients"]:::http
        GRPCC["gRPC Clients"]:::grpc
        SWAG["OpenAPI/Swagger UI"]:::http
    end

    subgraph "Gateway Layer"
        PROXY["Generated Reverse Proxy Server"]:::gateway
        click PROXY "https://github.com/grpc-ecosystem/grpc-gateway/tree/main/examples/internal/gateway"
        RUNTIME["Runtime Package"]:::gateway
        click RUNTIME "https://github.com/grpc-ecosystem/grpc-gateway/tree/main/runtime"
        TRANSFORM["Request/Response Transformation"]:::gateway
        click TRANSFORM "https://github.com/grpc-ecosystem/grpc-gateway/blob/main/runtime/handler.go"
    end

    subgraph "Server Layer"
        GRPCS["gRPC Server"]:::grpc
        click GRPCS "https://github.com/grpc-ecosystem/grpc-gateway/tree/main/examples/internal/cmd/example-grpc-server"
        SVCIMPL["Service Implementations"]:::grpc
    end

    subgraph "Generation Layer"
        PROTOC["Protocol Buffer Compiler"]:::generator
        GENPLUGIN["Gateway Generator Plugin"]:::generator
        click GENPLUGIN "https://github.com/grpc-ecosystem/grpc-gateway/tree/main/protoc-gen-grpc-gateway"
        OPENPLUGIN["OpenAPI Generator Plugin"]:::generator
        click OPENPLUGIN "https://github.com/grpc-ecosystem/grpc-gateway/tree/main/protoc-gen-openapiv2"
        
        subgraph "Internal Components"
            DESC["Descriptor Handler"]:::internal
            click DESC "https://github.com/grpc-ecosystem/grpc-gateway/tree/main/internal/descriptor"
            HTTPRULE["HTTP Rule Parser"]:::internal
            click HTTPRULE "https://github.com/grpc-ecosystem/grpc-gateway/tree/main/internal/httprule"
            CODEGEN["Code Generation Utils"]:::internal
            click CODEGEN "https://github.com/grpc-ecosystem/grpc-gateway/tree/main/internal/codegenerator"
        end
        
        PROTO["Proto Files"]:::config
        ANNOT["Annotations"]:::config
        CONFIG["External Configs"]:::config
    end

    %% Request/Response Flow
    HTTP --> |HTTP Request| PROXY
    PROXY --> |Transform| RUNTIME
    RUNTIME --> |gRPC Call| GRPCS
    GRPCS --> |Response| RUNTIME
    RUNTIME --> |Transform| PROXY
    PROXY --> |HTTP Response| HTTP
    
    GRPCC --> GRPCS
    SWAG --> HTTP

    %% Generation Flow
    PROTO -.-> PROTOC
    PROTOC -.-> GENPLUGIN
    PROTOC -.-> OPENPLUGIN
    ANNOT -.-> GENPLUGIN
    CONFIG -.-> GENPLUGIN
    
    %% Internal Components Flow
    GENPLUGIN --- DESC
    GENPLUGIN --- HTTPRULE
    GENPLUGIN --- CODEGEN
    OPENPLUGIN --- DESC
    
    %% Generated Output Flow
    GENPLUGIN -.-> PROXY
    OPENPLUGIN -.-> SWAG

    %% Styling
    classDef http fill:#2196F3,color:white
    classDef grpc fill:#4CAF50,color:white
    classDef gateway fill:#FF9800,color:white
    classDef generator fill:#9C27B0,color:white
    classDef internal fill:#607D8B,color:white
    classDef config fill:#795548,color:white

    %% Legend
    subgraph Legend
        L1["HTTP/REST Component"]:::http
        L2["gRPC Component"]:::grpc
        L3["Gateway Component"]:::gateway
        L4["Generator Component"]:::generator
        L5["Internal Component"]:::internal
        L6["Configuration"]:::config
    end
```
