Home

Mazadak - Platform Overview

What is Mazadak?

Mazadak is a microservices-based e-commerce platform focused on auction-based commerce. Sellers can list products through auctions or fixed-price listings, buyers can bid or purchase directly, and the platform handles the entire transaction lifecycle.

What it does:

• Time-bound auctions with bidding and proxy bid support
• Fixed-price product listings with inventory management
• Shopping cart and checkout workflows
• Payment processing via Stripe
• Email notifications for important events

Core Capabilities

Auctions:

• Bidding with proxy bid automation
• Reserve pricing and anti-sniping
• Cascading winner selection if payment fails

Shopping:

• Product catalog with categories and ratings
• Shopping cart
• Fixed-price inventory with reservation system

Platform Infrastrcture:

• Event-driven architecture (Kafka)
• Distributed workflows (Temporal)
• Centralized config (Spring Cloud Config)
• Service discovery (Eureka)
• API Gateway with JWT auth and rate limiting

System Architecture

Mazadak is composed of 11 Spring Boot services, supported by Kafka for messaging, Temporal for workflows, and a full observability stack.

Services:

• 8 business services (Auctions, Orders, Cart, Inventory, Product Catalog, Payment, Users, Notifications)
• 3 infrastructure services (API Gateway, Eureka, Config Server)
• Kafka for async events
• Temporal for distributed workflows
• Postgres for persistence (Database per-service)
• Observability stack (Prometheus, Grafana, Tempo, Loki)
• External integrations (Stripe, Cloudinary)

Design principles:

• Services own their data and communicate via REST + events
• Temporal orchestrates distributed transactions, not events
• Outbox pattern for reliable event delivery
• JWT auth at gateway, authorization per service
• Config externalized to Config Server

See Architecture Overview for details.

Repository Structure

The platform is split into multiple repositories to enforce clear ownership boundaries and independent development lifecycles.

Business Services:

Repository	Purpose	Tech
auctions	Auction lifecycle, bidding	Spring Boot, Postgres, Kafka
orders	Order processing, checkout workflows	Spring Boot, Postgres, Kafka, Temporal
cart	Shopping cart	Spring Boot, Kafka, Postgres
inventory	Inventory tracking, reservations	Spring Boot, Postgres, Kafka
product-catalog	Products, categories, ratings	Spring Boot, Postgres, Kafka, Temporal
payment-service	Payment processing (Stripe)	Spring Boot, Postgres, Kafka, Stripe
user-service	Users, auth	Spring Boot, Postgres, Kafka
notifications	Email delivery	Spring Boot, Kafka, Thymeleaf

Infrastructure Services:

Repository	Purpose	Tech
gateway	API Gateway, auth, rate limiting	Spring Cloud Gateway, Resilience4j
eureka-server	Service discovery	Spring Cloud Eureka
config-server	Config management	Spring Cloud Config

Supporting Repositories:

Repository	Purpose
common-module	Shared libraries (exceptions, utilities) published to GitHub Packages
configs	YAML configs for all services, read by Config Server
infrastructure	Docker Compose files for deployment
UI	React frontend
.github	Shared GitHub Actions workflows + this wiki
project-management	GitHub Project board for tracking work

Notes:

• common-module is published to GitHub Packages Maven registry and imported by all services
• configs is a Git repo that Config Server reads from
• infrastructure contains the Docker Compose setup which is currently the primary deployment setup
• .github is the organization repo that holds shared CI/CD workflows and this wiki

Deployment

The project is to be deployed with Docker Compose. All services, infra (Postgres, Kafka, Temporal, Eureka, Config Server), and observability (Prometheus, Grafana, Tempo, Loki) run as containers.

• Deployment files are in the infrastructure repo
• Docker images published to GitHub Container Registry: ghcr.io/mazaadak/<service-name>
• Built automatically via CI/CD on push to main

Where to Go Next

Overview:

• Architecture Overview - System design and data flows

Platform:

• Eventing Model - Kafka, outbox pattern, event catalog
• Workflow Orchestration - Temporal workflows
• Security Model - JWT auth and authorization
• CI/CD - Build pipelines and deployment

Services:

• Auctions - Bidding, proxy bids, auction lifecycle
• Orders - Checkout workflows
• Product Catalog - Products, categories, listings
• Cart - Shopping cart
• Inventory - Stock tracking
• Payment - Stripe integration
• Users - Auth and user management
• Notifications - Email delivery
• API Gateway - Routing, auth, rate limiting
• Service Discovery - Eureka Service discovery
• Config Server - Config management

Contributing:

• Environment Setup - Local setup
• Contribution Guide - How to contribute