# lukasz-antoniak/grpc-etcd architecture

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

- Interactive diagram: https://gitdiagram.com/lukasz-antoniak/grpc-etcd
- Repository: https://github.com/lukasz-antoniak/grpc-etcd

## Overview

##### Main components
- gRPC Server:
- Represents the primary service endpoint.
- Uses a “ListenableServerState” (see classes like ListenableServerStateImpl and ServerStateListener) to decorate the gRPC server lifecycle.
- Integrates with ETCD by notifying server startup and shutdown events.
- ETCD Cluster:
- An external service discovery/data store that holds the service keys and configuration.
- Stores both service configuration (as JSON) and each service endpoint key registered by running servers.
- gRPC Client:
- Configured to use a custom NameResolverProvider (i.e., EtcdNameResolverProvider) that connects to ETCD.
- Uses the resolved endpoint data and service configuration for client-side load balancing.
- ETCD Service Registry & Name Resolver:
- On the server side, the EtcdServiceRegistry is responsible for registering/deregistering service instances in ETCD.
- On the client side, the EtcdNameResolver handles querying ETCD for updates on available service endpoints.

##### Relationships and interactions
- Server Lifecycle & Registration:
- When a server starts, the ListenableServerState is used to listen for server lifecycle events.
- The server notifies its ETCD service registry (EtcdServiceRegistry) upon startup, which writes its endpoint key (using the common keyPrefix) to ETCD.
- When the server shuts down, the service is deregistered similarly.
- Client Service Discovery:
- The client initializes by registering the EtcdNameResolverProvider with the gRPC NameResolverRegistry.
- It then builds a ManagedChannel that targets the “etcd://…” URI.
- The custom NameResolver polls ETCD for active service instances and updates the client channel with changes.
- Data Flow:

##### Important architectural patterns and design principles
- Separation of concerns is evident: the server handles its own registration via lifecycle events, while the client is agnostic about server details and relies on ETCD for endpoint resolution.
- The “lookaside” load balancing pattern is central: ETCD acts as an intermediary for service discovery.
- There is a clear distinction between control and data flow—server branches are responsible for registering with ETCD, and client branches for resolving endpoints based on dynamically updated ETCD keys.
- The system uses a modular design where ETCD-based functionality is encapsulated in dedicated components such as EtcdServiceRegistry, EtcdNameResolver, and their providers.

##### Relevant technologies and frameworks
- Java (as the programming language)
- gRPC (for both server and client communication)
- ETCD (as the service discovery mechanism)
- Maven (as the build and dependency management tool)
- Additional libraries or frameworks like the ETCD client library used to connect to an ETCD cluster

##### Final advice for the principal software engineer
- Be detailed in capturing each individual component that plays a role in the load balancing system.
- Don’t oversimplify; include the internal interaction between lifecycle management and service registration, as well as the client’s use of a custom NameResolver.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Server Side"
        A["gRPC Server"]:::server
        B["ListenableServerState"]:::server
        C["ListenableServerStateImpl"]:::server
        D["ServerStateListener"]:::server
        E["EtcdServiceRegistry"]:::server
    end

    subgraph "ETCD Cluster"
        I["ETCD Cluster"]:::etcd
        F["Configuration"]:::etcd
        G["Endpoint"]:::etcd
        H["EndpointMetadata"]:::etcd
    end

    subgraph "Client Side"
        J["gRPC Client"]:::client
        K["EtcdNameResolver"]:::client
        L["EtcdNameResolverProvider"]:::client
    end

    %% Server-side interactions
    A -->|"startup/shutdown"| E
    %% Lifecycle management internal components (for clarity)
    A --> B
    A --> C
    A --> D
    
    %% Server registers with ETCD
    E -->|"register/deregister"| I

    %% ETCD Cluster distributes service discovery data
    I -->|"discovery-data"| K

    %% gRPC Client receives updates from the name resolver
    K -->|"update-endpoints"| J
    L -->|"provides-resolver"| J

    %% ETCD Domain Object connections (illustrative grouping)
    I --> F
    I --> G
    I --> H

    %% Click Events for Server-side Lifecycle Management
    click B "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/lifecycle/ListenableServerState.java"
    click C "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/lifecycle/ListenableServerStateImpl.java"
    click D "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/lifecycle/ServerStateListener.java"

    %% Click Event for ETCD Service Registry
    click E "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/loadbalancing/etcd/server/EtcdServiceRegistry.java"

    %% Click Events for Client-side Name Resolver
    click K "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/loadbalancing/etcd/client/EtcdNameResolver.java"
    click L "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/loadbalancing/etcd/client/EtcdNameResolverProvider.java"

    %% Click Events for ETCD Domain Objects
    click F "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/loadbalancing/etcd/domain/Configuration.java"
    click G "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/loadbalancing/etcd/domain/Endpoint.java"
    click H "https://github.com/lukasz-antoniak/grpc-etcd/blob/master/src/main/java/io/grpc/extension/loadbalancing/etcd/domain/EndpointMetadata.java"

    %% Style Definitions
    classDef server fill:#AEDFF7,stroke:#0275d8,stroke-width:2px;
    classDef client fill:#C8F7C5,stroke:#28a745,stroke-width:2px;
    classDef etcd fill:#F7C8C8,stroke:#d9534f,stroke-width:2px;
```
