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

```bash
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`)