3ybactuk-marketplace-go-service-project/README.md

Marketplace Microservices Platform

A Go-based microservices marketplace platform built step-by-step across modules. It showcases HTTP & gRPC APIs, databases, concurrency, messaging, and observability.

Services

• Cart — user shopping cart (HTTP).
• LOMS — Logistics & Order Management (gRPC + HTTP gateway): orders, stock, reservation.
• Comments — item comments (HTTP).
• Notifier — Kafka consumer that processes order events.

Infra: PostgreSQL, Kafka, Docker Compose, Prometheus, Grafana, OpenTelemetry.

---

Features by Module

1. Go Basics (Cart)

   • HTTP API: add/delete/clear/list cart.
   • Logging middleware, request validation, client retries.
   • In-memory repository.

2. Testing in Go

   • Unit tests for use cases & repository (minimock).
   • Coverage target ≥ 60%.
   • Benchmarks + e2e tests (selected handlers).

3. Inter-service Communication (LOMS)

   • gRPC API: OrderCreate, OrderInfo, OrderPay, OrderCancel, StocksInfo.
   • Cart → LOMS via gRPC (checkout & stock checks).
   • proto-gen-validate interceptor, HTTP gateway, Swagger UI.

4. Databases

   • LOMS uses PostgreSQL with migrations.
   • Transactional order creation.
   • SQLC for type-safe queries.

5. Concurrency

   • Parallel product lookups with a custom errgroup.
   • Client-side RPS limiting (10 RPS), context cancellation.
   • Mutex-protected in-memory stores.

6. Messaging & Outbox (extended)

   • Kafka outbox for order domain events (see loms/internal/infra/messaging/kafka_outbox).
   • Notifier consumes and processes events (notifier/internal/infra/messaging/kafka).

7. Observability (extended)

   • OpenTelemetry tracing, Prometheus metrics, Grafana dashboards.
   • gRPC/HTTP middleware for logging/metrics/tracing.

8. Production-Ready Enhancements (extended)

   • Dockerized services & Makefile automation.
   • Graceful shutdowns, race/leak checks.
   • CI-friendly lint/tests/migrations.
   • End-to-end integration tests.

---

Tech Stack

Go 1.23 • HTTP • gRPC + gRPC-Gateway • Swagger • PostgreSQL • SQLC • Kafka • OpenTelemetry • Prometheus • Grafana • Docker & Docker Compose • minimock

---

Project Structure (high-level)

/cart         # HTTP cart service, clients to LOMS & product-service, tests
/loms         # gRPC LOMS service (orders, stocks), DB layer (sqlc), gateway, swagger
/comments     # Comments service (HTTP, Postgres repository)
/notifier     # Kafka consumer (order events)
/prometheus   # Prometheus config
/grafana_data # Local Grafana storage
/docker-compose.yaml
/Makefile     # build/run/test targets

(See service-specific folders for configs, db/migrations, and Makefile targets.)

---

Run Locally

make run-all

Starts services (cart, loms, comments, notifier) plus dependencies (PostgreSQL, Kafka), applies migrations, and exposes UIs.

Default ports

• Cart HTTP: http://localhost:8080
• LOMS gRPC-Gateway & Swagger: http://localhost:8081
• Product service (mock): http://localhost:8082/docs
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000

Auth to product-service via X-API-KEY: testToken.

---

Key APIs

Cart (HTTP)

• POST /user/{user_id}/cart/{sku} — add item (validates via product-service; checks stock via LOMS).
• DELETE /user/{user_id}/cart/{sku} — remove item.
• DELETE /user/{user_id}/cart — clear cart.
• GET /user/{user_id}/cart — list cart (sorted by SKU).
• POST /checkout/{user_id} — create order in LOMS from cart.

LOMS (gRPC + HTTP Gateway)

• OrderCreate, OrderInfo, OrderPay, OrderCancel
• StocksInfo — available to buy (total − reserved)

Swagger (when enabled):

• LOMS: http://localhost:8081/docs
• Product mock: http://localhost:8082/docs

---

Happy Path (Example Flow)

1. POST /user/{user_id}/cart/{sku} — Add item to cart (checks product exists and stock is sufficient).
2. GET /user/{user_id}/cart — Verify cart contents.
3. POST /checkout/{user_id} — Create an order in LOMS.
4. POST /order/pay (LOMS) — Pay the order with body { "orderId": <id> }.
5. Optionally, POST /order/cancel (LOMS) before payment to cancel the order.

---

Development

Makefile highlights

• make run-all — build & run full stack
• make test — unit tests (minimock)
• make lint — lint (incl. cyclomatic/cognitive complexity)
• make cover — coverage report
• make gen — proto & SQLC codegen

Testing

• Unit tests for use cases & repositories
• e2e tests for selected handlers
• Benchmarks for in-memory storage
• Race detector & goroutine leak checks (where applicable)

---

Observability

• Tracing via OpenTelemetry (internal/infra/tracing)
• Metrics via Prometheus (/prometheus/prometheus.yml)
• Dashboards in Grafana (/grafana_data)