# hieuminh65/go-grpc-graphql-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/hieuminh65/go-grpc-graphql-microservices
- Repository: https://github.com/hieuminh65/go-grpc-graphql-microservices

## Overview

##### Project type and purpose
- This is a Go‑based microservices system with three domain services (Account, Catalog, Order) communicating over gRPC and exposed to clients via a single GraphQL API gateway.
- Purpose: demonstrate a production‑style architecture (microservices + API gateway) with per‑service persistence and containerized deployment via Docker Compose.

##### File structure
- Top‑level directories:
- account/ – Account microservice (gRPC proto, server, client, SQL migrations, Dockerfiles)
- catalog/ – Catalog microservice (gRPC, Elasticsearch storage, Dockerfiles)
- order/ – Order microservice (gRPC, server, client, SQL migrations, Dockerfiles)
- graphql/ – GraphQL gateway (gqlgen schema, resolvers, Go server, Dockerfile)
- Other files:
- docker-compose.yaml – defines all containers and networks
- assets/ – documentation thumbnail
- go.mod, go.sum – dependency management
- Each service has its own Dockerfile(s) for app and DB, plus protobuf definitions in a `/pb` package.

##### README for additional insights
- Confirms three services each with their own database:
- Account & Order → PostgreSQL
- Catalog → Elasticsearch
- GraphQL playground on port 8000
- gRPC used for inter‑service calls and for gateway‑to‑services calls

##### Main components
a. GraphQL API Gateway
b. Account Service (gRPC server + Postgres)
c. Catalog Service (gRPC server + Elasticsearch)
d. Order Service (gRPC server + Postgres)
e. Internal gRPC communication channels
f. Datastores (2× PostgreSQL, 1× Elasticsearch)
g. Docker Compose network overlay
h. (Optional) External client invoking GraphQL

##### Relationships and data flow
- Client → GraphQL Gateway (HTTP/GraphQL)
- Gateway → each microservice (gRPC calls)
- Microservices → their respective databases (SQL/HTTP API for Elasticsearch)
- Optionally, Order Service may call Account or Catalog Services for validation or enrichment via gRPC
- All services are containerized and communicate over a Docker‑managed network

##### Architectural patterns and design principles
- Microservices: each bounded context in its own repo folder, own Docker image, own datastore
- API Gateway: single entry point, schema stitching via gqlgen resolvers mapping to gRPC clients
- Polyglot persistence: Postgres for relational data, Elasticsearch for search & catalog queries
- Separation of concerns: repo layer, service layer, transport (gRPC) layer, migrations, Dockerfiles

##### Technologies, frameworks, and libraries
- Go modules for dependency management
- gRPC + Protocol Buffers (protoc, `pb` packages)
- gqlgen for GraphQL server and codegen
- PostgreSQL, Elasticsearch
- Docker & Docker Compose

##### Detail without over‑splitting
- Inter‑service flows, persistence boundaries, and the gateway contract.

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef external fill:#92D14F
    classDef gateway fill:#F9DC5C
    classDef service fill:#6ECFF6
    classDef db fill:#F2C94C
    classDef compose stroke:#999,stroke-dasharray:5 5

    A["External Client"]:::external

    subgraph "Docker Compose" 
        direction TB
        DC["docker-compose.yaml"]:::compose

        G["GraphQL API Gateway\n(gqlgen)"]:::gateway

        AC["Account Service\n(gRPC + Postgres)"]:::service
        CA["Catalog Service\n(gRPC + Elasticsearch)"]:::service
        OR["Order Service\n(gRPC + Postgres)"]:::service

        PG1["Postgres\n(Account)"]:::db
        ES["Elasticsearch"]:::db
        PG2["Postgres\n(Order)"]:::db
    end

    A -->|"HTTP/GraphQL"| G
    G -->|"gRPC"| AC
    G -->|"gRPC"| CA
    G -->|"gRPC"| OR
    AC -->|"SQL"| PG1
    OR -->|"SQL"| PG2
    CA -->|"HTTP API"| ES
    OR -->|"gRPC (optional)"| AC
    OR -->|"gRPC (optional)"| CA

    click G "https://github.com/hieuminh65/go-grpc-graphql-microservices/tree/master/graphql/"
    click AC "https://github.com/hieuminh65/go-grpc-graphql-microservices/tree/master/account/"
    click CA "https://github.com/hieuminh65/go-grpc-graphql-microservices/tree/master/catalog/"
    click OR "https://github.com/hieuminh65/go-grpc-graphql-microservices/tree/master/order/"
    click DC "https://github.com/hieuminh65/go-grpc-graphql-microservices/blob/master/docker-compose.yaml"
```
