# nhuson/microservice-grpc-gin-golang architecture

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

- Interactive diagram: https://gitdiagram.com/nhuson/microservice-grpc-gin-golang
- Repository: https://github.com/nhuson/microservice-grpc-gin-golang

## Overview

##### Project Type and Purpose
- This is a Go‑based microservices system combining Gin (HTTP REST) and gRPC.
- It implements three services: a Gateway (REST façade) and two backend services (Posts, Users), each with its own private database (“sidecar” pattern).
- Purpose: expose a unified REST API to clients, forward calls internally via gRPC to dedicated services, each handling its own data and persistence.

##### File Structure Analysis
- Top‑level:
- core/ shared configs, DB connection logic, helper functions, and common protobuf definitions
- services/ contains three subfolders: gateway, posts, users
- Dockerfile, docker-compose.yaml, Jenkinsfile for containerization and CI/CD
- main.go at root is likely a bootstrap or older entry point (services each have their own main.go)
- services/gateway:
- handler/ Gin handlers for HTTP endpoints (posts.go, users.go)
- routers/ router definitions mapping paths to handlers
- middleware/ auth, logging, etc.
- validator/ request validation logic
- services/posts and services/users:
- handler/ gRPC server handlers
- repo/ database access layer (entity, CRUD methods)
- pb/ protocol buffer definitions (.proto) and generated Go code

##### Insights from README
- Each backend service communicates via gRPC.
- The gateway exposes REST endpoints on port 8080.

##### Main Components
- External Client (mobile app, browser, other services)
- API Gateway Service (Gin HTTP server)
- Posts Service (gRPC server + private DB)
- Users Service (gRPC server + private DB)
- Shared Core Library (configs, helpers, common protobuf schemas)
- CI/CD Pipeline (Jenkins)
- Container Infrastructure (Docker, docker‑compose, Kubernetes or Docker host)

##### Relationships and Data Flows
- External Client sends HTTP requests to API Gateway over REST.
- Gateway middleware authenticates and validates, then routes to appropriate HTTP handler.
- Handlers invoke gRPC clients (auto‑generated from core/pb) to the Posts or Users service.
- Posts/Users service handlers receive gRPC calls, use repo layer to read/write their private database.
- Responses flow back gRPC → Gateway → HTTP response to client.

##### Architectural Patterns and Principles
- Microservice architecture (each service is independently deployable, owns its data store).
- Sidecar pattern (each service encapsulates its own database).
- API Gateway pattern (REST to gRPC translation, central authentication).
- Hexagonal/Onion style inside each service (handler → business logic → repo).
- Protocol Buffers for IDL and message serialization.

##### Key Technologies and Frameworks
- Go language
- Gin Gonic for REST in Gateway
- gRPC + Protobuf for internal RPC
- Docker & docker‑compose for containerization
- Jenkins for CI/CD
- Gopkg.toml (dep) for dependency management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["External Client"]:::external

    %% API Gateway Service
    subgraph "API Gateway Service"
        GateMain["main.go"]:::gateway
        GateHandler["handler/"]:::gateway
        GateRouters["routers/api.go"]:::gateway
        GateMiddleware["middleware/auth.go"]:::gateway
        GateValidator["validator/"]:::gateway
    end

    %% Posts Service
    subgraph "Posts Service"
        PostsMain["main.go"]:::backend
        PostsHandler["handler/post.go"]:::backend
        PostsProto["pb/post.proto\npb/post.pb.go"]:::backend
        PostsRepo["repo/"]:::backend
        PostsDB["Posts DB"]:::db
    end

    %% Users Service
    subgraph "Users Service"
        UsersMain["main.go"]:::backend
        UsersHandler["handler/user.go"]:::backend
        UsersProto["pb/user.proto\npb/user.pb.go"]:::backend
        UsersRepo["repo/"]:::backend
        UsersDB["Users DB"]:::db
    end

    %% Shared Core Library
    Core["Shared Core Library"]:::core

    %% Infrastructure
    subgraph "Container & CI/CD"
        Dockerfile["Dockerfile"]:::infra
        Compose["docker-compose.yaml"]:::infra
        Jenkins["Jenkinsfile"]:::infra
        Gopkg["Gopkg.toml"]:::infra
        RootMain["root main.go"]:::infra
    end

    %% Connections
    Client -->|"REST/JSON"| GateRouters
    GateRouters --> GateHandler
    GateHandler --> GateValidator
    GateHandler --> GateMiddleware
    GateHandler -->|"gRPC/Protobuf"| PostsMain
    GateHandler -->|"gRPC/Protobuf"| UsersMain

    PostsMain --> PostsHandler
    PostsHandler --> PostsRepo
    PostsRepo --> PostsDB

    UsersMain --> UsersHandler
    UsersHandler --> UsersRepo
    UsersRepo --> UsersDB

    Core --> GateMain
    Core --> PostsMain
    Core --> UsersMain

    RootMain --> Jenkins
    Gopkg --> Jenkins
    Jenkins --> Dockerfile
    Dockerfile --> Compose
    Compose --> GateMain
    Compose --> PostsMain
    Compose --> UsersMain

    %% Click Events
    click GateMain "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/gateway/main.go"
    click GateHandler "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/gateway/handler/handler.go"
    click GateHandler "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/gateway/handler/posts.go"
    click GateHandler "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/gateway/handler/users.go"
    click GateRouters "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/gateway/routers/api.go"
    click GateMiddleware "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/gateway/middleware/auth.go"
    click GateValidator "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/gateway/validator/post.go"
    click GateValidator "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/gateway/validator/user.go"

    click PostsMain "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/posts/main.go"
    click PostsHandler "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/posts/handler/post.go"
    click PostsProto "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/posts/pb/post.proto"
    click PostsProto "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/posts/pb/post.pb.go"
    click PostsRepo "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/posts/repo/post.go"
    click PostsRepo "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/posts/repo/post_entity.go"

    click UsersMain "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/users/main.go"
    click UsersHandler "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/users/handler/user.go"
    click UsersProto "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/users/pb/user.proto"
    click UsersProto "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/users/pb/user.pb.go"
    click UsersRepo "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/users/repo/user.go"
    click UsersRepo "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/services/users/repo/user_entity.go"

    click Core "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/core/configs/config.go"
    click Core "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/core/db/database.go"
    click Core "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/core/heplers/crypto.go"
    click Core "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/core/heplers/lib.go"
    click Core "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/core/heplers/response.go"
    click Core "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/core/pb/objectid.proto"
    click Core "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/core/pb/tagger.proto"

    click Dockerfile "https://github.com/nhuson/microservice-grpc-gin-golang/tree/master/Dockerfile"
    click Compose "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/docker-compose.yaml"
    click Jenkins "https://github.com/nhuson/microservice-grpc-gin-golang/tree/master/Jenkinsfile"
    click Gopkg "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/Gopkg.toml"
    click RootMain "https://github.com/nhuson/microservice-grpc-gin-golang/blob/master/main.go"

    %% Styles
    classDef external fill:#ffe082,stroke:#bb6600;
    classDef gateway fill:#82b1ff,stroke:#2962ff;
    classDef backend fill:#b9f6ca,stroke:#00c853;
    classDef db fill:#ffccbc,stroke:#ff5722,shape:cylinder;
    classDef core fill:#e1bee7,stroke:#8e24aa;
    classDef infra fill:#cfd8dc,stroke:#455a64;
```
