# tusmasoma/go-microservice-k8s architecture

> Architecture diagram of the GitHub repository tusmasoma/go-microservice-k8s, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tusmasoma/go-microservice-k8s
- Repository: https://github.com/tusmasoma/go-microservice-k8s

## Overview

##### Project Type and Purpose
- This is a microservices application written in Go. It uses Kubernetes (Minikube for local development) to deploy multiple services – catalog, customer, order, and gateway – each of which is containerized using Docker.
- The README explains how to deploy these services on Minikube, indicating that the project is geared toward a cloud-native, containerized microservices architecture. The use of Kubernetes manifests (YAML files under the k8s directory) and Dockerfiles suggests a production-like deployment environment.
- The existence of gRPC protocol buffers (in the proto directory) indicates that the services may communicate via gRPC for high-performance RPC calls.

##### Analyzing the File Structure
- Top-Level Directories:
- "go/services": Contains individual microservices (catalog, customer, order, gateway) with separate folders for API handling, command-line entry points (main.go), database access (both real and mock), and entities.
- "docker": Includes Dockerfiles for each microservice and a shared MySQL instance, indicating containerized deployment for easy scaling and isolation.
- "k8s": Contains Kubernetes deployment and service YAMLs for each microservice, shared MySQL configuration, and ingress rules.
- "proto": Houses gRPC protocol definitions for all services, used to generate server and client stubs.
- Other folders like "go/pkg" and "migrations" indicate common libraries (for configuration, logging, request/response handling, etc.) and database initialization scripts.

##### Main Components
a. Microservices:
- Catalog Service (handles catalog items)
- Customer Service (manages customer data)
- Order Service (handles orders)
- Gateway Service (acts as the entry point – likely the API gateway – routing requests to other services)
b. Shared and External Components:
- MySQL Database: A shared stateful database running under Kubernetes (as seen in k8s/shared-mysql-statefulset.yaml and related files).
- Kubernetes Cluster: This encapsulates all deployments, service definitions, and ingress. Include the ingress controller (managed by Minikube addons) which facilitates external access.

##### Relationships and Interactions
- The Gateway Service is the external interface receiving incoming HTTP/gRPC requests. It routes these requests to the appropriate microservice (Catalog, Customer, or Order) based on the URL/path.
- Each microservice has its own API layer and interacts with its respective logic and data layers.
- All persistent data is stored in a shared MySQL instance, and each service’s database repository layer abstracts the connection to MySQL. Some services include a “mock” subdirectory for testing, indicating an abstraction layer.
- gRPC is used for inter-service or client-to-service communication, given the presence of protocol buffers and generated stubs in the proto folders.

##### Architectural Patterns and Design Principles
- Microservices: Individual services are decoupled, each handling domain-specific logic.
- API Gateway: The gateway service encapsulates web-level logic and provides a unified entry point.
- Containerization and Orchestration: Using Docker and Kubernetes to manage service deployments and scaling.
- Layering: Separation of concerns between API, business logic (entities and command handlers), and data access (database and repository layers).
- Testability: Provision of “mock” implementations in database packages points to an emphasis on unit and integration testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client"]:::client

    %% Kubernetes Cluster Subgraph
    subgraph "Kubernetes Cluster"
        direction TB
        Ingress["Ingress Controller\n(Kubernetes)"]:::infra
        APIGateway["Gateway Service\n(Go)"]:::service
        Catalog["Catalog Service\n(Go)"]:::service
        Customer["Customer Service\n(Go)"]:::service
        Order["Order Service\n(Go)"]:::service
    end

    %% MySQL Database
    DB["MySQL Database"]:::db

    %% gRPC Protocol Definitions
    gRPC["gRPC Protocol Definitions\n(proto)"]:::comm

    %% Project Configurations and Utilities Subgraph
    subgraph "Project Config & Utilities"
        direction TB
        Docker["Docker Container Configurations"]:::infra
        K8s["Kubernetes Deployment Manifests"]:::infra
        SharedLibs["Shared Libraries & Utilities"]:::utils
        Migrations["Database Migrations & Initialization Scripts"]:::utils
    end

    %% Data Flow Relationships
    Client -->|"HTTP/gRPC"| Ingress
    Ingress -->|"routes"| APIGateway
    APIGateway -->|"calls"| Catalog
    APIGateway -->|"calls"| Customer
    APIGateway -->|"calls"| Order

    Catalog -->|"db access"| DB
    Customer -->|"db access"| DB
    Order -->|"db access"| DB

    Catalog -->|"uses"| gRPC
    Customer -->|"uses"| gRPC
    Order -->|"uses"| gRPC

    %% Configuration Application Flow
    K8s -->|"applies deployment"| Ingress

    %% Styles
    classDef service fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef db fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef infra fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef comm fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef client fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef utils fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;

    %% Click Events for Component Mapping
    click Catalog "https://github.com/tusmasoma/go-microservice-k8s/tree/main/go/services/catalog"
    click Customer "https://github.com/tusmasoma/go-microservice-k8s/tree/main/go/services/customer"
    click Order "https://github.com/tusmasoma/go-microservice-k8s/tree/main/go/services/order"
    click APIGateway "https://github.com/tusmasoma/go-microservice-k8s/tree/main/go/services/gateway"
    click gRPC "https://github.com/tusmasoma/go-microservice-k8s/tree/main/proto"
    click Docker "https://github.com/tusmasoma/go-microservice-k8s/tree/main/docker"
    click K8s "https://github.com/tusmasoma/go-microservice-k8s/tree/main/k8s"
    click SharedLibs "https://github.com/tusmasoma/go-microservice-k8s/tree/main/go/pkg"
    click Migrations "https://github.com/tusmasoma/go-microservice-k8s/tree/main/migrations"
```
