# elfpuck/grpc-http architecture

> Architecture diagram of the GitHub repository elfpuck/grpc-http, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elfpuck/grpc-http
- Repository: https://github.com/elfpuck/grpc-http

## Overview

##### Project Type and Purpose
- This is an open‐source “developer tool” consisting of three protoc plugins (protoc-gen-go-http, protoc-gen-go-model, protoc-gen-swagger) plus a small Go runtime library (elfHttp) that wires up generated HTTP endpoints to a gRPC backend.
- Its purpose is to take .proto definitions and:
- generate Go model structs,
- generate HTTP gateway handlers,
- generate Swagger OpenAPI specs,
all in one protoc invocation.

##### File Structure
- Top level:
- elfHttp/         ← Go library providing HTTP server, routing, service registration
- protoc-gen-go-http/
- protoc-gen-go-model/
- protoc-gen-swagger/
- Each plugin folder contains a main.go (the plugin entry point) + tpl.go (the code templates).
- There’s a makefile and go.mod/go.sum for build and dependency management.

##### README Insights
- Installation: “go get” each plugin.
- Invocation: `protoc --go_out=plugins=grpc --go-http_out=... --go-model_out=... --swagger_out=... foo.proto`
- Usage snippet shows how the generated HTTP code calls into elfHttp.New(), registers services, and runs on an HTTP port.
- Swagger customization comes via protobuf annotations in swagger.proto.

##### Main Components and Their Relationships
A. Build‐Time Code Generation Flow
1. Input:
- .proto files (with optional swagger options)
2. Executor:
- protoc compiler
- Plugins invoked in order:
- protoc-gen-go (generates gRPC server & client stubs)
- protoc-gen-go-http
- protoc-gen-go-model
- protoc-gen-swagger
3. Plugins:
- Read the FileDescriptorSet from protoc stdin
- Apply Go template code (tpl.go)
- Emit .pb.go, _http.pb.go, _model.pb.go, swagger.json files
4. Output:
- Generated Go source code & swagger/spec files

B. Runtime HTTP ↔ gRPC Gateway Flow
1. elfHttp Library:
- elfHttp.New() creates a router + HTTP server
- e.Service("demo") returns a ServiceRegistrar
- Generated code calls RegisterXxxFromEndpoint(service, addr)
2. HTTP Server:
- Incoming HTTP requests → elfHttp routes → marshals to gRPC calls
3. gRPC Backend:
- gRPC server listens on its own port
- Business logic implemented in your service
4. Swagger UI / Spec:
- swagger.json served or embedded for client consumption

##### Architectural Patterns and Design Principles
- Plugin Architecture: each protoc‐gen‐XXX is a standalone executable conforming to protoc plugin protocol.
- Template‐Driven Codegen: separation of core logic (main.go) and templates (tpl.go).
- Layered Runtime: HTTP layer (elfHttp) → gRPC stub → business handlers.
- Single Responsibility: each plugin does one type of generation.

##### Elements
- Rectangles for processes (protoc, plugins, HTTP server, gRPC server)
- Rounded rectangles for libraries (elfHttp)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Build-Time Phase
  subgraph "Build-Time Phase"
    PROTOL[".proto Files"]:::artifact
    PROTOC["protoc Compiler"]:::build
    PROTOL --> PROTOC

    subgraph "Plugins"
      PGOG["protoc-gen-go"]:::build

      PGHTTP["protoc-gen-go-http"]:::build
      PGHTTP_MAIN["main.go"]:::build
      PGHTTP_TPL["tpl.go"]:::build

      PGMODEL["protoc-gen-go-model"]:::build
      PGM_MAIN["main.go"]:::build
      PGM_TPL["tpl.go"]:::build

      PSG["protoc-gen-swagger"]:::build
      PSG_MAIN["main.go"]:::build
      PSG_TPL["tpl.go"]:::build
      PSG_SWAGGERGO["swagger.go"]:::build
      PSG_OPT["options/swagger.proto"]:::build
      PSG_PB["options/swagger.pb.go"]:::build
    end

    PROTOC --> PGOG
    PROTOC --> PGHTTP
    PROTOC --> PGMODEL
    PROTOC --> PSG

    PGHTTP --> PGHTTP_MAIN
    PGHTTP --> PGHTTP_TPL
    PGMODEL --> PGM_MAIN
    PGMODEL --> PGM_TPL
    PSG --> PSG_MAIN
    PSG --> PSG_TPL
    PSG --> PSG_SWAGGERGO
    PSG --> PSG_OPT
    PSG --> PSG_PB

    PROTOC -->|"stdin/stdout"| PGHTTP
    PROTOC -->|"stdin/stdout"| PGMODEL
    PROTOC -->|"stdin/stdout"| PSG

    subgraph "Outputs"
      GO_PB[".pb.go Files"]:::artifact
      HTTP_PB["_http.pb.go Files"]:::artifact
      MODEL_PB["_model.pb.go Files"]:::artifact
      SWAGGER["swagger.json"]:::artifact
    end

    PGOG --> GO_PB
    PGHTTP --> HTTP_PB
    PGMODEL --> MODEL_PB
    PSG --> SWAGGER

    subgraph "Project Files"
      GO_MOD["go.mod"]:::artifact
      GO_SUM["go.sum"]:::artifact
      MAKE["makefile"]:::artifact
      README["README.md"]:::artifact
      GITIGNORE[".gitignore"]:::artifact
    end
  end

  %% Runtime Phase
  subgraph "Runtime Phase"
    HTTP_CL["HTTP Client"]:::runtime
    ELF_DIR["elfHttp/"]:::runtime
    subgraph "elfHttp Library Files"
      ELF_ELF["elf.go"]:::runtime
      ELF_SERVICE["service.go"]:::runtime
      ELF_CTX["ctx.go"]:::runtime
      ELF_MODE["mode.go"]:::runtime
      ELF_MV["mv.go"]:::runtime
      ELF_TEST["elf_test.go"]:::runtime
    end
    HTTP_SERVER["HTTP Server"]:::runtime
    GRPC_STUB["gRPC Client Stub"]:::runtime
    GRPC_SERVER["gRPC Server"]:::runtime
    SWAG_UI["Swagger UI / Spec"]:::artifact

    HTTP_CL --> HTTP_SERVER
    HTTP_SERVER -->|"routes & marshals"| GRPC_STUB
    GRPC_STUB -->|"gRPC Calls"| GRPC_SERVER
    ELF_DIR --> HTTP_SERVER
    ELF_DIR --> GRPC_STUB
    ELF_DIR --> SWAG_UI
  end

  %% Click Events
  click PGHTTP "https://github.com/elfpuck/grpc-http/tree/master/protoc-gen-go-http/"
  click PGHTTP_MAIN "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-go-http/main.go"
  click PGHTTP_TPL "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-go-http/tpl.go"
  click PGMODEL "https://github.com/elfpuck/grpc-http/tree/master/protoc-gen-go-model/"
  click PGM_MAIN "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-go-model/main.go"
  click PGM_TPL "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-go-model/tpl.go"
  click PSG "https://github.com/elfpuck/grpc-http/tree/master/protoc-gen-swagger/"
  click PSG_MAIN "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-swagger/main.go"
  click PSG_TPL "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-swagger/tpl.go"
  click PSG_SWAGGERGO "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-swagger/swagger.go"
  click PSG_OPT "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-swagger/options/swagger.proto"
  click PSG_PB "https://github.com/elfpuck/grpc-http/blob/master/protoc-gen-swagger/options/swagger.pb.go"
  click ELF_DIR "https://github.com/elfpuck/grpc-http/tree/master/elfHttp/"
  click ELF_ELF "https://github.com/elfpuck/grpc-http/blob/master/elfHttp/elf.go"
  click ELF_SERVICE "https://github.com/elfpuck/grpc-http/blob/master/elfHttp/service.go"
  click ELF_CTX "https://github.com/elfpuck/grpc-http/blob/master/elfHttp/ctx.go"
  click ELF_MODE "https://github.com/elfpuck/grpc-http/blob/master/elfHttp/mode.go"
  click ELF_MV "https://github.com/elfpuck/grpc-http/blob/master/elfHttp/mv.go"
  click ELF_TEST "https://github.com/elfpuck/grpc-http/blob/master/elfHttp/elf_test.go"
  click GO_MOD "https://github.com/elfpuck/grpc-http/blob/master/go.mod"
  click GO_SUM "https://github.com/elfpuck/grpc-http/blob/master/go.sum"
  click MAKE "https://github.com/elfpuck/grpc-http/tree/master/makefile"
  click README "https://github.com/elfpuck/grpc-http/blob/master/README.md"
  click GITIGNORE "https://github.com/elfpuck/grpc-http/blob/master/.gitignore"

  %% Styles
  classDef build fill:#f9f,stroke:#333,stroke-width:1px
  classDef runtime fill:#9ff,stroke:#333,stroke-width:1px
  classDef artifact fill:#ff9,stroke:#333,stroke-width:1px
```
