# rformagio/java-grpc architecture

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

- Interactive diagram: https://gitdiagram.com/rformagio/java-grpc
- Repository: https://github.com/rformagio/java-grpc

## Overview

##### Project type and purpose
- This is a distributed Java application demonstrating a gRPC-based microservice interaction using Spring Boot. It consists of two separate services:
a. grpc-client – a RESTful API that accepts HTTP GET requests for postal codes (CEP), invokes a local gRPC stub, and returns address data.
b. grpc-server – a gRPC server that implements the CepService defined in a .proto file, looks up address data in a map, and responds to gRPC calls.

##### File structure
- Top-level directories:
- grpc-client – Spring Boot REST app + gRPC client stub
- grpc-server – Spring Boot gRPC server
- Each service has:
- Dockerfile & init.sh – containerization scripts
- pom.xml – Maven configuration with Spring Boot, grpc-spring-boot-starter and protobuf‐maven‐plugin
- src/main/proto – CepService.proto shared by both client and server
- src/main/java/br/com/rformagio/grpc – entry points (GrpcClient.java, GrpcServer.java), controllers/services
- src/main/resources/application.yml – service configuration
- The top-level pom.xml orchestrates multi‐module builds.

##### README for additional insights
- The README explains the role of Protobuf, the .proto file, and gRPC stub/skeleton generation via Maven plugins.
- It outlines the runtime flow: HTTP → stub → gRPC server → in-memory map lookup → response.

a. Components
1. HTTP Client (e.g., Browser or curl)
2. REST API Layer (grpc-client – AddressController)
3. gRPC Stub & Channel (AddressClientService + generated gRPC classes)
4. Network (TCP on port 6565 or configured port)
5. gRPC Server (grpc-server – GrpcServer entrypoint)
6. Business Logic (CepServiceImp)
7. Data Store (in-memory Map)
b. Relationships & Data Flow
– HTTP GET /address/{cep} → AddressController
– Controller calls AddressClientService.getAddressByCep(cep)
– Service uses gRPC stub to open channel → sends AddressRequest(cep)
– Server’s GrpcServer skeleton dispatches to CepServiceImp.getAddress
– CepServiceImp looks up Map[cep] → builds AddressResponse
– Response flows back over gRPC → stub → AddressClientService → controller → HTTP response JSON
c. Architectural Patterns & Principles
– Client-Server RPC pattern (stub/skeleton)
– Separation of concerns: REST front end vs. RPC backend
– Protobuf for interface definition (IDL)
– Containerizable microservices (Dockerfiles present)
d. Key Technologies & Frameworks
– Java 11+
– Spring Boot + net.devh grpc‐spring‐boot‐starter
– gRPC / Protocol Buffers
– Maven for build & code generation
– Docker for containerization

4. Inside grpc-server: show GrpcServer skeleton receiving calls → delegating to CepServiceImp → in-memory Map.
– Application code vs. generated code vs. data store vs. network interface.
7. Maven build step generating stubs/skeletons from .proto.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    HTTPClient["HTTP Client (Browser/curl)"]:::external

    %% Client Service Container
    subgraph "grpc-client Service" 
        direction TB
        GrpcClient["GrpcClient\n(entry point)"]:::clientEntry
        ClientConfig["application.yml"]:::config
        AddressController["AddressController"]:::controller
        AddressClientService["AddressClientService"]:::service
        Stub["gRPC Stub\n(generated)"]:::stub
        DockerfileClient["Dockerfile"]:::script
        InitClient["init.sh"]:::script
    end

    %% Protobuf Contract Layer
    subgraph "gRPC Contract" 
        direction TB
        Proto["CepService.proto"]:::contract
    end

    %% Server Service Container
    subgraph "grpc-server Service" 
        direction TB
        GrpcServer["GrpcServer\n(entry point)"]:::serverEntry
        CepServiceImp["CepServiceImp\n(business logic)"]:::service
        Map["In-Memory Map"]:::data
        ServerConfig["application.yml"]:::config
        DockerfileServer["Dockerfile"]:::script
        InitServer["init.sh"]:::script
    end

    %% Multi-Module Build
    MultiModule["pom.xml\n(multi-module build)"]:::build

    %% Data Flows
    HTTPClient -->|"GET /address/{cep} (port 8080)"| AddressController
    AddressController -->|"calls"| AddressClientService
    AddressClientService -->|"uses stub"| Stub
    Stub -->|"gRPC call (port 6565)"| GrpcServer
    GrpcServer -->|"dispatch to"| CepServiceImp
    CepServiceImp -->|"lookup"| Map
    Map -->|"AddressResponse"| CepServiceImp
    CepServiceImp -->|"return result"| GrpcServer
    GrpcServer -->|"gRPC response"| Stub
    Stub -->|"response"| AddressClientService
    AddressClientService -->|"return JSON"| AddressController
    AddressController -->|"HTTP 200"| HTTPClient

    %% Build Dependencies
    MultiModule -.-> GrpcClient
    MultiModule -.-> GrpcServer

    %% Click Events
    click AddressController "https://github.com/rformagio/java-grpc/blob/master/grpc-client/src/main/java/br/com/rformagio/grpc/api/AddressController.java"
    click AddressClientService "https://github.com/rformagio/java-grpc/blob/master/grpc-client/src/main/java/br/com/rformagio/grpc/service/AddressClientService.java"
    click Proto "https://github.com/rformagio/java-grpc/blob/master/grpc-client/src/main/proto/CepService.proto"
    click GrpcClient "https://github.com/rformagio/java-grpc/blob/master/grpc-client/src/main/java/br/com/rformagio/grpc/GrpcClient.java"
    click GrpcServer "https://github.com/rformagio/java-grpc/blob/master/grpc-server/src/main/java/br/com/rformagio/grpc/GrpcServer.java"
    click CepServiceImp "https://github.com/rformagio/java-grpc/blob/master/grpc-server/src/main/java/br/com/rformagio/grpc/service/CepServiceImp.java"
    click ClientConfig "https://github.com/rformagio/java-grpc/blob/master/grpc-client/src/main/resources/application.yml"
    click ServerConfig "https://github.com/rformagio/java-grpc/blob/master/grpc-server/src/main/resources/application.yml"
    click DockerfileClient "https://github.com/rformagio/java-grpc/tree/master/grpc-client/Dockerfile"
    click InitClient "https://github.com/rformagio/java-grpc/blob/master/grpc-client/init.sh"
    click DockerfileServer "https://github.com/rformagio/java-grpc/tree/master/grpc-server/Dockerfile"
    click InitServer "https://github.com/rformagio/java-grpc/blob/master/grpc-server/init.sh"
    click MultiModule "https://github.com/rformagio/java-grpc/blob/master/pom.xml"

    %% Styles
    classDef external fill:#D6DBDF,stroke:#566573
    classDef clientEntry fill:#AED6F1,stroke:#1F618D
    classDef controller fill:#A3E4D7,stroke:#148F77
    classDef service fill:#ABEBE0,stroke:#117A65
    classDef stub fill:#F9E79F,stroke:#B7950B
    classDef contract fill:#FAD7A0,stroke:#B9770E
    classDef serverEntry fill:#A9DFBF,stroke:#196F3D
    classDef data fill:#F5CBA7,stroke:#B03A2E
    classDef config fill:#D2B4DE,stroke:#6C3483
    classDef script fill:#E5E7E9,stroke:#616A6B
    classDef build fill:#F4E1A5,stroke:#B7950B
```
