{"id":24707321,"url":"https://github.com/jordanmarcelino/learn-go-microservices","last_synced_at":"2025-10-25T15:32:21.290Z","repository":{"id":274335383,"uuid":"922486715","full_name":"JordanMarcelino/learn-go-microservices","owner":"JordanMarcelino","description":"Learning building microservices application with Go","archived":false,"fork":false,"pushed_at":"2025-02-17T16:09:19.000Z","size":151,"stargazers_count":4,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-17T16:27:04.903Z","etag":null,"topics":["backend-api","cluster","gin","golang","grafana","kafka","mailhog","microservices","opentelemetry","postgresql","prometheus","rabbitmq","redis"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JordanMarcelino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-26T10:54:26.000Z","updated_at":"2025-02-17T16:09:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"8a109f7c-f3b9-43f5-a071-b4f919075c85","html_url":"https://github.com/JordanMarcelino/learn-go-microservices","commit_stats":null,"previous_names":["jordanmarcelino/learn-go-microservices"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanMarcelino%2Flearn-go-microservices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanMarcelino%2Flearn-go-microservices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanMarcelino%2Flearn-go-microservices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JordanMarcelino%2Flearn-go-microservices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JordanMarcelino","download_url":"https://codeload.github.com/JordanMarcelino/learn-go-microservices/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244912219,"owners_count":20530756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend-api","cluster","gin","golang","grafana","kafka","mailhog","microservices","opentelemetry","postgresql","prometheus","rabbitmq","redis"],"created_at":"2025-01-27T06:16:14.890Z","updated_at":"2025-10-25T15:32:21.237Z","avatar_url":"https://github.com/JordanMarcelino.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Go Microservices Simple E-Commerce Platform\n\nWelcome to my journey of building a scalable microservices architecture using Golang! This project will implement core microservices patterns with modern technologies.\n\n[![Go Version](https://img.shields.io/badge/go-%3E%3D1.23.4-blue.svg)](https://golang.org/)\n[![Docker](https://img.shields.io/badge/Docker-24.0+-blue.svg)](https://www.docker.com/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## ❓ How to Run\n\n1. Clone the repository\n\n```bash\ngit clone https://github.com/JordanMarcelino/learn-go-microservices.git\n```\n\n2. Start the Docker Compose\n\n```bash\nmake\n```\n\n3. Check the services\n\n```bash\ndocker compose ps\n```\n\n4. Import the Postman collection\n\n5. Test the APIs\n\n6. Stop the services\n\n```bash\nmake compose-down\n```\n\n## 🌟 Key Features\n\n-   **Event-Driven Architecture** with Kafka \u0026 RabbitMQ\n-   **Database Master-Slave Replica** with PostgreSQL Cluster\n-   **Observability** with OpenTelemetry \u0026 Grafana Stack\n-   **Production-Grade** Infrastructure Setup\n\n## 🏗 Architecture Overview\n\n```mermaid\ngraph TD\n  A[Client] --\u003e B[API Gateway]\n  subgraph Core Services\n    B --\u003e C[Auth Service]\n    B --\u003e D[Product Service]\n    B --\u003e E[Order Service]\n    B --\u003e F[Mail Service]\n  end\n\n  subgraph Data Layer\n    C --\u003e G[PostgreSQL Cluster]\n    D --\u003e H[PostgreSQL Cluster]\n    E --\u003e I[PostgreSQL Cluster]\n    E --\u003e J[Redis Cluster]\n  end\n\n  subgraph Event Bus\n    D --\u003e K[Kafka Cluster]\n    E --\u003e K\n    C --\u003e L[RabbitMQ Cluster]\n    F --\u003e L\n  end\n```\n\n## 🛠 Service Breakdown\n\n### 1. 🔐 Auth Service\n\n**Responsibilities**: User identity management and authentication\n\n```mermaid\nsequenceDiagram\n  participant Client\n  participant Gateway\n  participant AuthService\n  participant PostgreSQL\n  participant RabbitMQ\n\n  Client-\u003e\u003eGateway: POST /register\n  Gateway-\u003e\u003eAuthService: Forward request\n  AuthService-\u003e\u003ePostgreSQL: Create user (unverified)\n  AuthService-\u003e\u003eRabbitMQ: Publish verification event\n  RabbitMQ-\u003e\u003eMailService: Consume event\n  MailService-\u003e\u003eUser: Send verification email\n```\n\n**Key Features**:\n\n-   JWT-based authentication\n-   Email verification with 10-minute expiry\n-   Anti-spam protection (1-minute cooldown)\n-   CQRS pattern with master-slave replication\n-   Horizontal scaling with pgpool-II\n\n---\n\n### 2. 📦 Product Service\n\n**Responsibilities**: Product lifecycle management\n\n```mermaid\ngraph TD\n  A[Create Product] --\u003e B[Kafka: product-created]\n  C[Update Product] --\u003e D[Kafka: product-updated]\n  E[Order Created Event] --\u003e F[Reduce Stock]\n  B --\u003e G[Order Service]\n  D --\u003e G\n```\n\n**Key Features**:\n\n-   Real-time inventory synchronization\n-   Event sourcing for product changes\n-   CQRS pattern with master-slave replication\n\n---\n\n### 3. 🛒 Order Service\n\n**Responsibilities**: Order processing and fulfillment\n\n```mermaid\ngraph TD\n  A[Order Created] --\u003e B[Schedule Reminders]\n  A --\u003e C[Start 24h Countdown]\n  B --\u003e D[4h Reminder]\n  B --\u003e E[12h Reminder]\n  B --\u003e F[22h Reminder]\n  C --\u003e G[Expiration Check]\n\n  D --\u003e H[Send Email via Mail Service]\n  E --\u003e H\n  F --\u003e H\n  G --\u003e I{Payment Status?}\n\n  I --\u003e|Paid| J[Mark Order Completed]\n  I --\u003e|Unpaid| K[Cancel Order]\n  K --\u003e L[Restock Inventory]\n  K --\u003e M[Send Cancellation Email]\n```\n\n### 1. Order Creation with Delayed Messages\n\n```mermaid\nsequenceDiagram\n  participant Client\n  participant Gateway\n  participant OrderService\n  participant PostgreSQL\n  participant RabbitMQ\n  participant Kafka\n\n  Client-\u003e\u003eGateway: POST /orders\n  Gateway-\u003e\u003eOrderService: Forward request\n  OrderService-\u003e\u003eRedis: SETNX lock:request_id\n  Redis--\u003e\u003eOrderService: Lock acquired\n  OrderService-\u003e\u003ePostgreSQL: Create order (status=PENDING)\n  OrderService-\u003e\u003eRabbitMQ: Publish delayed messages\n  Note over RabbitMQ: 4h, 12h, 22h delays\n  OrderService-\u003e\u003eKafka: order.created\n  OrderService-\u003e\u003eRedis: DEL lock:request_id\n  Kafka-\u003e\u003eProductService: Reserve stock\n```\n\n### 2. Payment Reminder Execution Flow\n\n```mermaid\nsequenceDiagram\n  participant RabbitMQ\n  participant OrderService\n  participant PostgreSQL\n  participant MailService\n\n  RabbitMQ-\u003e\u003eOrderService: Reminder event\n  OrderService-\u003e\u003ePostgreSQL: Get order status\n  alt Status = PENDING\n    OrderService-\u003e\u003eMailService: Send payment reminder\n    MailService-\u003e\u003eUser: Email reminder\n  else Status = PAID/CANCELLED\n    OrderService-\u003e\u003eRabbitMQ: Acknowledge message\n  end\n```\n\n### 3. Order Expiration Handling\n\n```mermaid\nsequenceDiagram\n  participant RabbitMQ\n  participant OrderService\n  participant PostgreSQL\n  participant Kafka\n  participant ProductService\n\n  RabbitMQ-\u003e\u003eOrderService: Expiration event (24h)\n  OrderService-\u003e\u003ePostgreSQL: Check payment status\n  alt Unpaid\n    OrderService-\u003e\u003ePostgreSQL: Update status=CANCELLED\n    OrderService-\u003e\u003eKafka: order.cancelled\n    Kafka-\u003e\u003eProductService: Restock items\n    OrderService-\u003e\u003eMailService: Notify cancellation\n  else Paid\n    OrderService-\u003e\u003ePostgreSQL: Update status=COMPLETED\n  end\n```\n\n## 🧠 Key Design Decisions\n\n1. **Delayed Message Implementation**\n\n    ```mermaid\n    graph LR\n      A[Order Service] --\u003e|Publish with delay| B[RabbitMQ]\n      B --\u003e|x-delayed-message plugin| C[Delayed Exchange]\n      C --\u003e|TTL 4h| D[Reminder Queue]\n      C --\u003e|TTL 12h| E[Reminder Queue]\n      C --\u003e|TTL 22h| F[Reminder Queue]\n      C --\u003e|TTL 24h| G[Expiration Queue]\n    ```\n\n2. **State Transition Diagram**\n\n    ```mermaid\n    stateDiagram-v2\n      [*] --\u003e PENDING\n      PENDING --\u003e PAID: Payment received\n      PENDING --\u003e CANCELLED: 24h timeout\n      PAID --\u003e COMPLETED: Order fulfilled\n      CANCELLED --\u003e [*]\n      COMPLETED --\u003e [*]\n    ```\n\n**Key Features**:\n\n-   Redis distributed locking for idempotency\n-   Event-driven order processing\n-   Delayed message handling with RabbitMQ\n-   State transition management with PostgreSQL\n\n---\n\n### 4. 📧 Mail Service\n\n**Responsibilities**: Asynchronous email processing\n\n**Key Features**:\n\n-   RabbitMQ consumer\n-   Template-based email rendering\n-   Send retry mechanism with exponential backoff\n-   MailHog integration for development\n\n---\n\n### 5. 🌉 API Gateway\n\n**Responsibilities**: Unified API entrypoint\n\n**Key Features**:\n\n-   JWT validation middleware\n-   Rate limiting per service\n-   Request/Response transformation\n-   Prometheus metrics collection\n\n## 🏭 Infrastructure Architecture\n\n```mermaid\ngraph TD\n  subgraph Database Layer\n    A[PostgreSQL Cluster] --\u003e B[Auth DB]\n    A --\u003e C[Product DB]\n    A --\u003e D[Order DB]\n    B --\u003e E[1 Master + 2 Replicas]\n    C --\u003e F[1 Master + 2 Replicas]\n    D --\u003e G[1 Master + 2 Replicas]\n  end\n\n  subgraph Message Brokers\n    H[RabbitMQ Cluster] --\u003e I[3 Nodes]\n    J[Kafka Cluster] --\u003e K[3 Brokers]\n  end\n\n  subgraph Caching\n    L[Redis Cluster] --\u003e M[3 Masters + 3 Replicas]\n  end\n\n  subgraph Observability\n    N[Prometheus]\n    O[Loki]\n    P[Tempo]\n    Q[Grafana]\n    R[OpenTelemetry]\n  end\n```\n\n## 🔍 Observability Stack\n\n```mermaid\ngraph TD\n  A[Services] --\u003e B[OpenTelemetry]\n  B --\u003e C[Metrics]\n  B --\u003e D[Traces]\n  B --\u003e E[Logs]\n  C --\u003e F[Prometheus]\n  D --\u003e G[Tempo]\n  E --\u003e H[Loki]\n  F --\u003e I[Grafana]\n  G --\u003e I\n  H --\u003e I\n```\n\n**Monitoring Features**:\n\n-   Real-time service metrics\n-   Distributed tracing across services\n-   Centralized logging with labels\n-   Performance dashboards per service\n\n## 🛠️ Technology Stack\n\n**Languages \u0026 Frameworks**\n\n-   Go 1.23+\n-   Gin Web Framework\n\n**Databases**\n\n-   PostgreSQL 16 with pgpool-II\n-   Bitnami Redis Latest Cluster\n\n**Message Brokers**\n\n-   Bitnami Kafka Latest Cluster\n-   RabbitMQ 4.0 Cluster\n\n**Infrastructure**\n\n-   Docker Swarm\n-   HAProxy for load balancing\n-   MailHog SMTP server\n\n**Observability**\n\n-   Prometheus\n-   Grafana\n-   Loki\n-   Tempo\n-   OpenTelemetry\n\n## 📈 Deployment Architecture\n\n```mermaid\ngraph TD\n  A[Load Balancer] --\u003e B[API Gateway Cluster]\n  B --\u003e C[Auth Service Cluster]\n  B --\u003e D[Product Service Cluster]\n  B --\u003e E[Order Service Cluster]\n  B --\u003e F[Mail Service Cluster]\n\n  C --\u003e G[PostgreSQL Cluster]\n  D --\u003e H[PostgreSQL Cluster]\n  E --\u003e I[PostgreSQL Cluster]\n  E --\u003e J[Redis Cluster]\n\n  C --\u003e K[RabbitMQ Cluster]\n  D --\u003e L[Kafka Cluster]\n  E --\u003e L\n  F --\u003e K\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordanmarcelino%2Flearn-go-microservices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjordanmarcelino%2Flearn-go-microservices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjordanmarcelino%2Flearn-go-microservices/lists"}