SUSTech Merch Store Microservices

Wed, 01 Oct 2025 00:00:00 +0000

Background

Time: Oct 2025
Context: Assignment 2 for SUSTech “Distributed and Cloud Computing” (module: Services & API Architectures).
Repository: Tsurumalu/SUSTech-Merch-Store

Goal

Build a microservice-based online merch store for SUSTech-branded products. The system exposes RESTful APIs to clients, isolates database access behind a gRPC service, and streams operational logs to Kafka through a dedicated logging service—all orchestrated with Docker Compose.

Architecture

Three application services run alongside shared infrastructure:

Service	Role	Protocol / Stack
API Service	REST gateway, JWT auth, business orchestration	Flask, OpenAPI 3.0
DB Service	User, product, and order persistence	gRPC + psycopg2
Logging Service	Centralized log ingestion	gRPC → Kafka

Infrastructure containers: PostgreSQL 17 (persistent storage), Zookeeper + Kafka (log channel log-channel).

1
2
3


Client ──HTTP──► API Service ──gRPC──► DB Service ──► PostgreSQL
 │
 └──gRPC──► Logging Service ──► Kafka

REST API

Defined in openapi.yaml and implemented in Flask:

Dialog: GET / greeting endpoint
UserManager: register, deactivate, get user, update profile, login
ProductManager: list products, get product by ID
OrderManager: place order, cancel order, get order details

Protected routes use JWT (Bearer token, HS256, 24-hour expiration). Authentication failures and key operations are forwarded to the logging service.

Data Model

PostgreSQL schema (db-init/init.sql):

products: SUSTech Hoodie, Water Bottle, Notebook (pre-seeded with stock)
users: sid, username, email, password hash
orders: user–product linkage with quantity cap (1–3 per order) and computed total_price

Implementation Highlights

Service decomposition: API layer never talks to PostgreSQL directly; all DB operations go through the gRPC AssistantService.
Connection pooling: DB service uses psycopg2.pool.ThreadedConnectionPool for concurrent gRPC requests.
Structured logging: API service streams LogMessage events (register, login, order, auth failures) to the logging service, which publishes JSON payloads to Kafka via confluent_kafka.
Containerized deployment: compose.yaml wires api-server, db-server, and logging-server with health-checked Kafka/Zookeeper and volume-backed Postgres init scripts.
Dev utilities: Makefile helpers for local psql, DB reset, and Kafka log streaming.

Tech Stack

Python (Flask, gRPC, PyJWT)
PostgreSQL 17
Apache Kafka (Confluent Platform 7.7)
Docker & Docker Compose
OpenAPI 3.0
Protocol Buffers (gRPC service definitions)

Docker on Zitao Liao

Projects