# bigcommerce/gruf architecture

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

- Interactive diagram: https://gitdiagram.com/bigcommerce/gruf
- Repository: https://github.com/bigcommerce/gruf

## Overview

##### Project type and purpose
- gruf is an open-source Ruby gem that wraps the gRPC Ruby library to provide a streamlined server and client framework for building gRPC services in Ruby (and Rails) applications. It is not a full-stack app but a middleware library designed for integration and extensibility.

##### File structure
- Top-level artifacts
- bin/console, bin/gruf, gruf.gemspec, Gemfile, Rakefile – gem entry points, build & test scripts
- lib/gruf – core library code
- lib/gruf/client – client API, error handling, configuration
- lib/gruf/controllers – abstract controller classes (health, request handling, service binding)
- lib/gruf/interceptors – server- and client-side interceptor chain for auth, logging, instrumentation, connection reset, etc.
- lib/gruf/hooks – lifecycle hooks (before_request, after_response) with registry and executors
- lib/gruf/serializers – error serializers for JSON, metadata transport
- lib/gruf/integrations – Rails Railtie integration
- lib/gruf/server.rb – wrapper around the gRPC Ruby server
- lib/gruf/logger, grpc_logger, timer – unified logging and timing utilities
- Configuration files (YARD, RuboCop, CircleCI, GitHub templates) point to a well-maintained open-source project with CI, code style, and documentation.

##### README for additional insights
- Features: abstracted controllers, full interceptor support, robust client error handling, authentication, TLS support, error serialization, execution timings
- Supported environments: Ruby 3.0–3.4, gRPC 1.10+, Rails and non-Rails usage

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Services"
        GRPC["gRPC Ruby Library"]:::external
        LINKERD["Linkerd (Service Mesh)"]:::external
    end

    subgraph "Client Layer"
        CLIENT_API["Gruf::Client API"]:::core
        SYNC_CLIENT["Synchronized Client Wrapper"]:::core
        CLIENT_INTER["Client Interceptor Chain"]:::middleware
    end
    CLIENT_API -->|"uses"| CLIENT_INTER
    CLIENT_INTER -->|"invokes"| GRPC

    subgraph "Transport Layer"
        GRPC
    end

    subgraph "Server Layer"
        INSTR_GRPC["Instrumentable gRPC Server"]:::core
        GRUF_SERVER["Gruf Server Wrapper"]:::core
        SERVER_INTER["Server Interceptor Chain"]:::middleware
    end
    GRPC -->|"receives"| INSTR_GRPC
    INSTR_GRPC --> GRUF_SERVER
    GRUF_SERVER --> SERVER_INTER

    subgraph "Interceptors"
        INT_BASE["Interceptor Base"]:::middleware
        INT_REG["Interceptor Registry"]:::middleware
        SERVER_INTER
        CLIENT_INTER
        INT_CONTEXT["Context Interceptor"]:::middleware
        INT_TIMER["Timer Interceptor"]:::middleware
        INT_AUTH["Basic Auth Interceptor"]:::middleware
        INT_AR["ActiveRecord Connection Reset"]:::middleware
        INT_INST_META["Metadata Timer"]:::middleware
        INT_INST_STATSD["StatsD Interceptor"]:::middleware
        INT_REQ_LOG["Request Logging Interceptor"]:::middleware
        RAILS_RELOADER["Rails Reloader"]:::middleware
    end
    INT_BASE --> INT_REG
    INT_REG --> SERVER_INTER
    INT_REG --> CLIENT_INTER
    SERVER_INTER --> INT_CONTEXT
    SERVER_INTER --> INT_TIMER
    SERVER_INTER --> INT_AUTH
    SERVER_INTER --> INT_AR
    SERVER_INTER --> INT_INST_META
    SERVER_INTER --> INT_INST_STATSD
    SERVER_INTER --> INT_REQ_LOG
    SERVER_INTER --> RAILS_RELOADER

    subgraph "Controllers"
        CTRL_BASE["Base Controller"]:::controllers_or_serializers
        CTRL_HEALTH["Health Controller"]:::controllers_or_serializers
        CTRL_REQUEST["Request Controller"]:::controllers_or_serializers
        CTRL_BINDER["Service Binder"]:::controllers_or_serializers
        CTRL_AUTOLOAD["Controllers Autoloader"]:::controllers_or_serializers
    end
    SERVER_INTER -->|"dispatches"| CTRL_BASE
    CTRL_BASE --> CTRL_HEALTH
    CTRL_BASE --> CTRL_REQUEST
    CTRL_BASE --> CTRL_BINDER
    CTRL_AUTOLOAD --> CTRL_BASE

    subgraph "Hooks"
        HOOK_REG["Hooks Registry"]:::middleware
        HOOK_EXEC["Hooks Executor"]:::middleware
        HOOK_BASE["Base Hook"]:::middleware
    end
    CTRL_REQUEST -->|"before/after"| HOOK_REG
    HOOK_REG --> HOOK_EXEC
    HOOK_EXEC --> CTRL_REQUEST
    HOOK_BASE --> HOOK_EXEC

    subgraph "Serializers"
        SERIAL_BASE["Error Serializer Base"]:::controllers_or_serializers
        SERIAL_JSON["JSON Error Serializer"]:::controllers_or_serializers
    end
    SERVER_INTER --> SERIAL_BASE
    SERIAL_BASE --> SERIAL_JSON

    subgraph "Integrations"
        INTEGRATION["Rails Railtie"]:::external
    end
    INTEGRATION -.-> CONFIG

    subgraph "Utilities"
        CONFIG["Configuration Module"]:::utils
        LOGGER["Logger"]:::utils
        GRPC_LOGGER["gRPC Logger"]:::utils
        TIMER_UTIL["Timer"]:::utils
        LOGGABLE["Loggable"]:::utils
    end
    CLIENT_INTER --> LOGGER
    SERVER_INTER --> LOGGER
    SERVER_INTER --> TIMER_UTIL
    CLIENT_INTER --> TIMER_UTIL
    CONFIG --> CLIENT_API
    CONFIG --> GRUF_SERVER

    subgraph "CLI"
        CLI_BIN["bin/gruf"]:::external
        CLI_EXEC["CLI Executor"]:::core
    end
    CLI_BIN --> CLI_EXEC

    GRUF_SERVER --> CTRL_BASE
    GRPC --> LINKERD

    click GRUF_SERVER "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/server.rb"
    click INSTR_GRPC "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/instrumentable_grpc_server.rb"
    click CLIENT_API "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/client.rb"
    click CLIENT_API "https://github.com/bigcommerce/gruf/tree/main/lib/gruf/client/"
    click SYNC_CLIENT "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/synchronized_client.rb"
    click CONFIG "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/configuration.rb"
    click CTRL_BASE "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/controllers/base.rb"
    click CTRL_HEALTH "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/controllers/health_controller.rb"
    click CTRL_REQUEST "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/controllers/request.rb"
    click CTRL_BINDER "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/controllers/service_binder.rb"
    click CTRL_AUTOLOAD "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/controllers/autoloader.rb"
    click INT_BASE "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/base.rb"
    click INT_REG "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/registry.rb"
    click SERVER_INTER "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/server_interceptor.rb"
    click CLIENT_INTER "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/client_interceptor.rb"
    click INT_CONTEXT "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/context.rb"
    click INT_TIMER "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/timer.rb"
    click INT_AUTH "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/authentication/basic.rb"
    click INT_AR "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/active_record/connection_reset.rb"
    click INT_INST_META "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/instrumentation/output_metadata_timer.rb"
    click INT_INST_STATSD "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/instrumentation/statsd.rb"
    click INT_REQ_LOG "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/instrumentation/request_logging/interceptor.rb"
    click RAILS_RELOADER "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/interceptors/rails/reloader.rb"
    click HOOK_REG "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/hooks/registry.rb"
    click HOOK_EXEC "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/hooks/executor.rb"
    click HOOK_BASE "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/hooks/base.rb"
    click SERIAL_BASE "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/serializers/errors/base.rb"
    click SERIAL_JSON "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/serializers/errors/json.rb"
    click INTEGRATION "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/integrations/rails/railtie.rb"
    click LOGGER "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/logger.rb"
    click GRPC_LOGGER "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/grpc_logger.rb"
    click TIMER_UTIL "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/timer.rb"
    click LOGGABLE "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/loggable.rb"
    click CLI_EXEC "https://github.com/bigcommerce/gruf/blob/main/lib/gruf/cli/executor.rb"

    classDef core fill:#D0E6FF,stroke:#0284C7,color:#000
    classDef middleware fill:#E6F4EA,stroke:#238636,color:#000
    classDef controllers_or_serializers fill:#FFE6D9,stroke:#D65A31,color:#000
    classDef external fill:#F3E8FF,stroke:#7C3AED,color:#000
    classDef utils fill:#F0F0F0,stroke:#6B7280,color:#000
```
