# jdk-plus/spring-boot-starter-grpc architecture

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

- Interactive diagram: https://gitdiagram.com/jdk-plus/spring-boot-starter-grpc
- Repository: https://github.com/jdk-plus/spring-boot-starter-grpc

## Overview

##### Main Components
- gRPC Server Components:
- Auto-configuration classes (e.g., GrpcAutoConfiguration, GrpcServerFactory, GrpcServerLifecycle) which set up and manage the server.
- Annotation components (e.g., @GrpcService, EnableGrpcServer) that enable gRPC service exposure.
- Interceptor configuration for the server (global interceptors, service-specific interceptors defined via GrpcServiceInterceptorConfigurer).
- Service registration modules (IGrpcServiceRegister implementations) for registering and deregistering the node (using tools such as etcd).

- gRPC Client Components:
- Auto-configuration for the client (GrpcClientAutoConfiguration) with support for a default service address, name resolvers, and custom interceptors.
- Annotation-driven clients (e.g., @GrpcClient on stub injection) that allow for simplified remote call creation.
- Factories for creating different types of gRPC stubs (e.g., AsyncStubFactory, BlockingStubFactory, FutureStubFactory, StandardGrpcStubFactory, FallbackStubFactory).
- NameResolver and client configuration (GrpcNameResolver, GrpcNameResolverProvider, INameResolverConfigurer) for service discovery from external configuration centers.
- Client interceptors (e.g., GrpcClientBeanPostProcessor, ClientBytesMetaDataInterceptor, and marshallers) that handle request metadata, encryption, or other cross-cutting concerns.

- Support and Utility Components:
- Global interceptor registries (GlobalGrpcInterceptorRegistry) for both client and server.
- Common utility classes (GrpcUtils) and configuration property classes (GrpcPlusProperties, GrpcPlusClientProperties) that centralize configuration.
- Annotation definitions (the various annotations in the annotation package) to drive integration with the Spring context.
- Additional selectors for choosing between multiple server and client beans (GrpcClientSelector, GrpcServerSelector).

##### Relationships and Interactions
- For the Server side, show that the Spring Boot auto-configuration reads properties (from application.properties/yaml) and sets up the server components, registers the available gRPC service beans (annotated with @GrpcService), and then wires in defined interceptors.
- For the Client side, indicate that the auto-configuration and bean post-processors (GrpcClientBeanPostProcessor) scan and process fields annotated with @GrpcClient, creating stub instances through the various Stub Factories. Also show how the NameResolver and INameResolverConfigurer interfaces are utilized to fetch configuration information (even via external sources, e.g., etcd) for service discovery.
- From the application configuration → Auto-configuration classes.
- From Auto-configuration → Factory beans and Interceptors → Actual gRPC stub creation.
- From gRPC service calls on the client → gRPC Server (actual RPC call) → Business logic execution.
- From the service registration components to external configuration centers (like etcd) for registering and discovering service nodes.

##### Architectural Patterns and Principles
- Modularization: The separation into packages (client, server, global, factory, interceptor, etc) reflects a clean separation of concerns.
- Dependency Injection and Auto-configuration: Leveraging Spring Boot’s auto-configuration to wire everything together automatically.
- Annotation-driven development: Custom annotations drive the discovery and configuration of services and clients.

##### Relevant Technologies, Frameworks, and Libraries
- Spring Boot – for auto-configuration and dependency injection.
- gRPC – as the underlying RPC framework.
- (Optionally) etcd, zookeeper, or redis – for service registration and discovery (as demonstrated in the README sample code).
- Protobuf & the protobuf-maven-plugin – for code generation from .proto files.

##### Final Recommendation
- Start at the highest abstraction level (overall architecture) and then drill down to detailed components (like the factories and interceptors).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    AppConfig["Application Config (properties/yaml)"]:::config

    %% External Service Registration/Discovery
    ExternalConfig["External Config Center (e.g., etcd)"]:::external

    %% Common / Utility Components
    GrpcUtils["GrpcUtils"]:::common
    GrpcPlusProps["GrpcPlusProperties"]:::config

    %% gRPC Server Module
    subgraph "gRPC Server Module"
        GRPCAuto["GrpcAutoConfiguration"]:::server
        ServerFactory["GrpcServerFactory"]:::server
        ServerLifecycle["GrpcServerLifecycle"]:::server
        GrpcServiceAnnotation["@GrpcService Annotation"]:::annotation
        EnableServerAnnotation["@EnableGrpcServer Annotation"]:::annotation
        ServerInterceptor["GrpcServiceInterceptorConfigurer"]:::server
        ServiceRegister["IGrpcServiceRegister"]:::server
        GlobalInterceptorServer["GlobalGrpcInterceptorRegistry"]:::global
        GrpcPlusClientProps["GrpcPlusClientProperties"]:::config
        ServerSelector["GrpcServerSelector"]:::selector
    end

    %% gRPC Client Module
    subgraph "gRPC Client Module"
        ClientAuto["GrpcClientAutoConfiguration"]:::client
        GrpcClientAnnotation["@GrpcClient Annotation"]:::annotation
        EnableClientAnnotation["@EnableGrpcClient Annotation"]:::annotation
        ClientBeanPP["GrpcClientBeanPostProcessor"]:::client
        NameResolver["GrpcNameResolver & Provider"]:::client
        NameResolverConfigurer["INameResolverConfigurer"]:::client
        AsyncStub["AsyncStubFactory"]:::client
        BlockingStub["BlockingStubFactory"]:::client
        FutureStub["FutureStubFactory"]:::client
        StandardStub["StandardGrpcStubFactory"]:::client
        FallbackStub["FallbackStubFactory"]:::client
        ClientInterceptor["ClientBytesMetaDataInterceptor"]:::client
        AsciiMarshaller["DefaultAsciiMarshaller"]:::client
        BinaryMarshaller["DefaultBinaryMarshaller"]:::client
        GlobalInterceptorClient["GlobalGrpcInterceptorRegistry"]:::global
        ClientSelector["GrpcClientSelector"]:::selector
    end

    %% Connections for Server Module
    AppConfig -->|"loads"| GRPCAuto
    GRPCAuto -->|"creates"| ServerFactory
    GRPCAuto -->|"manages"| ServerLifecycle
    GRPCAuto -->|"reads annotations"| GrpcServiceAnnotation
    GRPCAuto -->|"reads annotations"| EnableServerAnnotation
    GRPCAuto -->|"configures"| ServerInterceptor
    GRPCAuto -->|"registers service"| ServiceRegister
    ServiceRegister -- "register/deregister" --> ExternalConfig
    GRPCAuto -->|"includes"| GlobalInterceptorServer

    %% Connections for Client Module
    AppConfig -->|"loads"| ClientAuto
    ClientAuto -->|"processes annotations"| GrpcClientAnnotation
    ClientAuto -->|"processes annotations"| EnableClientAnnotation
    ClientAuto -->|"scans for stubs"| ClientBeanPP
    ClientBeanPP -->|"uses factories"| AsyncStub
    ClientBeanPP -->|"uses factories"| BlockingStub
    ClientBeanPP -->|"uses factories"| FutureStub
    ClientBeanPP -->|"uses factories"| StandardStub
    ClientBeanPP -->|"uses factories"| FallbackStub
    ClientAuto -->|"configures"| NameResolver
    ClientAuto -->|"configures"| NameResolverConfigurer
    ClientAuto -->|"includes"| GlobalInterceptorClient
    ClientAuto -->|"selects client"| ClientSelector

    %% Common/Utility connections
    AppConfig -->|"configures"| GrpcPlusProps
    ClientBeanPP -->|"utilizes"| GrpcUtils

    %% Inter-service interaction (Client to Server)
    StandardStub -->|"initiates RPC call"| GRPCAuto

    %% External configuration flow for Name Resolution
    NameResolverConfigurer -- "fetch config" --> ExternalConfig

    %% Selector usage
    GRPCAuto -->|"selects server bean"| ServerSelector

    %% Styling Definitions
    classDef server fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef client fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef annotation fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef common fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef global fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
    classDef selector fill:#d6d8d9,stroke:#1b1e21,stroke-width:2px;

    %% Click Events for gRPC Server Components
    click GRPCAuto "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/global/GrpcAutoConfiguration.java"
    click ServerFactory "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/global/GrpcServerFactory.java"
    click ServerLifecycle "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/global/GrpcServerLifecycle.java"
    click GrpcServiceAnnotation "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/annotation/GrpcService.java"
    click EnableServerAnnotation "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/annotation/EnableGrpcServer.java"
    click ServerInterceptor "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/global/GrpcServiceInterceptorConfigurer.java"
    click ServiceRegister "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/common/IGrpcServiceRegister.java"
    click GlobalInterceptorServer "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/global/GlobalGrpcInterceptorRegistry.java"
    click ServerSelector "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/selector/GrpcServerSelector.java"
    click GrpcPlusProps "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/config/GrpcPlusProperties.java"

    %% Click Events for gRPC Client Components
    click ClientAuto "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/global/GrpcClientAutoConfiguration.java"
    click GrpcClientAnnotation "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/annotation/GrpcClient.java"
    click EnableClientAnnotation "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/annotation/EnableGrpcClient.java"
    click ClientBeanPP "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/GrpcClientBeanPostProcessor.java"
    click NameResolver "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/GrpcNameResolver.java"
    click NameResolverConfigurer "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/INameResolverConfigurer.java"
    click AsyncStub "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/factory/AsyncStubFactory.java"
    click BlockingStub "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/factory/BlockingStubFactory.java"
    click FutureStub "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/factory/FutureStubFactory.java"
    click StandardStub "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/factory/StandardGrpcStubFactory.java"
    click FallbackStub "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/factory/FallbackStubFactory.java"
    click ClientInterceptor "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/interceptor/ClientBytesMetaDataInterceptor.java"
    click AsciiMarshaller "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/interceptor/marshaller/DefaultAsciiMarshaller.java"
    click BinaryMarshaller "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/client/interceptor/marshaller/DefaultBinaryMarshaller.java"
    click GlobalInterceptorClient "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/global/GlobalGrpcInterceptorRegistry.java"
    click ClientSelector "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/selector/GrpcClientSelector.java"
    
    %% Click Event for Utility Classes
    click GrpcUtils "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/common/GrpcUtils.java"
    
    %% Click Event for GrpcPlusClientProperties
    click GrpcPlusClientProps "https://github.com/jdk-plus/spring-boot-starter-grpc/blob/master/src/main/java/plus/jdk/grpc/config/GrpcPlusClientProperties.java"
```
