Cart Service

Role-based shopping cart service built with Go, Gin, gRPC, PostgreSQL, Redis, and Kafka.

What This Service Provides

• Cart lifecycle: create, fetch, update, delete, merge
• Cart item management: add/update/remove and save-for-later
• Coupon apply/remove and checkout validation
• Order placement and order history APIs
• Cart sharing and cart version restore
• Role-based APIs on separate ports: admin, service-admin, supplier, customer
• gRPC server plus gRPC-Gateway bridge
• WebSocket cart sync endpoint
• Metrics, tracing, and dashboard stack via Docker Compose

Tech Stack

• Go 1.25.x
• Gin (REST), gRPC, grpc-gateway
• PostgreSQL (GORM)
• Redis
• Kafka (Sarama)
• OpenTelemetry + Jaeger
• Prometheus + Grafana + Alertmanager + Loki
• Swagger (swag)

Project Structure

cart-service/
  cmd/
    api/main.go                # Main app: REST + gRPC + gateway + role routers
    consumer/main.go           # Kafka consumer example
  config/                      # Env configuration loader
  docs/                        # Swagger docs (base + role-specific)
  internal/
    handlers/                  # HTTP handlers
    grpc/                      # gRPC server implementation
    middleware/                # Auth, rate limit, tracing, logging, CORS, headers
    models/                    # Domain models
    repository/                # Data access layer
    service/                   # Business logic
    websocket/                 # WebSocket sync hub
    jobs/                      # Background jobs (cleanup, price sync)
  migrations/                  # SQL migrations
  monitoring/                  # Prometheus/Grafana/Alertmanager/Loki configs
  pkg/                         # Shared packages (db, cache, kafka, metrics, tracing, etc.)
  proto/cart.proto             # gRPC contract
  scripts/                     # Utility scripts (token, swagger generation)
  tests/                       # integration, kafka, grpc, load tests

Ports

• 8081 Admin REST + Swagger + /health + /metrics
• 8082 Service Admin REST + Swagger + /health + /metrics
• 8083 Supplier REST + Swagger + /health + /metrics
• 8084 Customer REST + Swagger + /health + /metrics
• 8085 gRPC-Gateway
• 9090 gRPC server

Infrastructure ports from docker-compose.yml:

• 5432 PostgreSQL
• 6379 Redis
• 8005 Redis Stack UI
• 8006 Kafka UI
• 9091 Prometheus
• 3000 Grafana
• 16686 Jaeger UI
• 9093 Alertmanager
• 3100 Loki

API Overview

Customer/public routes (/api/v1, served on 8084):

• Auth: POST /auth/signup, POST /auth/login
• Cart public: POST /cart/create, GET /cart/guest/:session_id, GET /cart/:id, GET /cart/:id/summary, POST /cart/validate-checkout, GET /cart/coupon/:code, GET /cart/shared/:token
• Cart auth: GET /cart, POST /cart/items, PUT /cart/items/:id, DELETE /cart/items/:id, DELETE /cart/:id, POST /cart/merge, POST /cart/:id/share
• Cart versions: GET /cart/:id/versions, POST /cart/:id/versions/:version/restore
• Coupons/checkout: POST /cart/apply-coupon, DELETE /cart/remove-coupon, POST /cart/calculate, POST /cart/checkout
• Saved items: POST /cart/items/:id/save-for-later, GET /cart/saved
• Orders: POST /orders, GET /orders, GET /orders/:id, DELETE /orders/:id

Admin routes (/api/v1/admin, served on 8081):

• Carts/analytics/users/orders/requests management endpoints
• Examples: GET /carts, GET /carts/abandoned, GET /analytics, POST /cleanup/expired

Service admin routes (/api/v1/service-admin, served on 8082):

• Catalog visibility and request workflows
• Examples: GET /items, POST /requests/delete-item/:id, POST /requests/modify-item/:id

Supplier routes (/api/v1/supplier, served on 8083):

• GET /products, PUT /inventory/:id/quantity, PUT /products/:id/rate

WebSocket:

• GET /ws/cart (available on admin/customer routers)
• Test page: web-socket.html

gRPC API

Defined in proto/cart.proto:

• CreateCart
• GetCart
• AddItem
• UpdateItem
• RemoveItem
• ApplyCoupon
• Checkout

gRPC runs on localhost:9090, gateway on localhost:8085.

Prerequisites

• Go 1.25+
• Docker + Docker Compose
• make
• migrate CLI (for make migrate-* targets)
• Optional: swag, protoc, grpcurl, jq, k6

Quick Start

1. Clone and enter project.
2. Create local env file from example.
3. Start dependencies.
4. Apply migrations.
5. Run the API.

cp .env.example .env
docker-compose up -d postgres redis zookeeper kafka
make migrate-up
make run

To run everything (app + infra) in containers with hot reload:

docker-compose up -d

Useful Commands

From Makefile:

make run            # go run cmd/api/main.go
make build          # build binary to ./bin/cart-service
make test           # go test -v ./...
make docker-up      # docker-compose up -d
make docker-down    # docker-compose down
make docker-logs    # docker-compose logs -f
make migrate-up     # apply migrations
make migrate-down   # rollback migrations
make migrate-create name=<migration_name>
make proto          # regenerate protobuf + grpc + gateway code
make deps           # go mod download && go mod tidy

Swagger Docs

Role-specific Swagger docs are available at:

• http://localhost:8081/swagger/index.html
• http://localhost:8082/swagger/index.html
• http://localhost:8083/swagger/index.html
• http://localhost:8084/swagger/index.html

Regenerate role docs (PowerShell):

./scripts/generate-swagger.ps1

Testing

Unit/all tests:

go test -v ./...

Targeted suites:

go test -v ./tests/integration/...
go test -v ./tests/kafka/...

gRPC smoke script:

./tests/grpc/test_grpc.sh

Load test (k6):

k6 run tests/load/basic_load_test.js

Environment Variables

See .env.example for the complete list. Core variables:

• APP_PORT, GRPC_PORT
• POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_SSL_MODE
• REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DB
• KAFKA_BROKERS
• JWT_SECRET

Monitoring And Observability

• Prometheus config: monitoring/prometheus.yml
• Alert rules: monitoring/alert_rules.yml
• Grafana datasource: monitoring/grafana-datasources.yml
• Dashboard JSON: monitoring/grafana-dashboard.json
• Alertmanager config: monitoring/alertmanager.yml
• Loki config: monitoring/loki-config.yml

Notes

• cmd/api/main.go hardcodes role servers on ports 8081-8084, gRPC gateway 8085, and gRPC 9090.
• cmd/consumer/main.go is a separate Kafka consumer process you can run independently.
• scripts/generate_token.go can generate a JWT for local testing.