GoShop

A production-ready e-commerce application built with Go (REST + gRPC backend) and React (web frontend).

Architecture

The application runs two servers concurrently (backend) plus a React web frontend:

• HTTP (REST) — Gin framework, port 8888
• gRPC — port 8889, with JWT auth interceptor

Each domain (user, product, order, payment, notification) follows a ports-and-adapters layout:

internal/{domain}/
├── model/       # GORM models
├── dto/         # Request/response structs with validation tags
├── repository/  # Database access (depends on dbs.Database interface)
├── service/     # Business logic (depends on repository interfaces)
└── port/
    ├── http/    # Gin handlers and route registration
    └── grpc/    # gRPC handlers and server registration

Tech Stack

Backend

Frontend

Prerequisites

• Go 1.26+
• Node.js 18+
• PostgreSQL
• Redis

Docker Compose for local dependencies: docker-compose-template

Getting Started

1. Clone and configure

git clone https://github.com/quangdangfit/goshop.git
cd goshop
cp config.sample.yaml config.yaml

Edit config.yaml (lives at the repo root and is loaded from the working directory; override with CONFIG_FILE=/path/to/config.yaml):

environment: production
http_port: 8888
grpc_port: 8889
auth_secret: your-secret-key
database_uri: postgres://username:password@localhost:5432/goshop
redis_uri: localhost:6379
redis_password:
redis_db: 0

# Stripe (payments)
stripe_secret_key: sk_test_xxx
stripe_webhook_secret: whsec_xxx
stripe_publishable_key: pk_test_xxx

# SMTP (notifications — point at MailHog locally: host=localhost, port=1025)
smtp_host:
smtp_port: 25
email_from: [email protected]

2. Apply database migrations

The app no longer runs AutoMigrate — schema lives in versioned SQL files under migrations/ and is applied with golang-migrate.

brew install golang-migrate   # or: go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
DATABASE_URI="postgres://username:password@localhost:5432/goshop?sslmode=disable" make migrate-up

See migrations/README.md for conventions and the production / Kubernetes init-container pattern.

3. Run the backend

go run cmd/api/main.go

INFO    HTTP server is listening on PORT: 8888
INFO    GRPC server is listening on PORT: 8889

4. Run the web frontend

cd web
npm install
npm run dev

Web UI: http://localhost:3000

The frontend proxies all /api requests to the backend at http://localhost:8888, so both servers must be running.

5. Browse the API

Swagger UI: http://localhost:8888/swagger/index.html

API Reference

Auth

Addresses

Wishlist

Categories

Products

Orders

Coupons

Payments

Notifications

Cart is client-side only (persisted in the browser). Order creation accepts the full line items and the server re-validates products, prices, and stock.

Development

Run all unit tests with coverage

make unittest

Run a single test suite

go test ./internal/product/service/... -v -run TestProductServiceTestSuite

Run a single test case

go test ./internal/product/service/... -v -run TestProductServiceTestSuite/TestCreateSuccess

Run integration tests

Integration suites live under tests/integration/ (per-domain: order, payment, user, product, notification), are gated by the //go:build integration tag, and use testcontainers to spin up real Postgres / Redis / MailHog. They are invisible to make unittest / go test ./....

make integration
# = go test -tags=integration -timeout 9000s -v -coverprofile=coverage.integration.out ./tests/integration/...

Requirements: a running Docker daemon. The shared helpers (StartPostgres, StartRedis, NewHTTPEnv) live in tests/testutil/. CI runs the integration job in parallel with the unit job; both upload coverage to Codecov under the unittest / integration flags.

Database migrations

make migrate-up                  # apply all pending migrations
make migrate-down                # roll back the latest migration
make migrate-status              # print current schema version
make migrate-new name=add_index  # scaffold the next NNNN_*.{up,down}.sql pair

Set DATABASE_URI in your shell to override the default (postgres://postgres:test@localhost:5432/goshop?sslmode=disable).

Regenerate mocks

make mock

Regenerate Swagger docs

make doc

Regenerate proto (Uses https://buf.build)

cd proto && make build