Backend API · Personal Project

H-Phsar — B2B Marketplace API

Solo Developer — Backend 2026 — Present 1 developer

Source available

Spring Boot 3
Java 17
MyBatis
PostgreSQL
Spring Security
WebSocket

Project Summary

Problem

Wholesale trade between distributors and retailers still runs on phone calls and paper: orders get lost, prices stay opaque, and neither side has a record of what was agreed. H-Phsar (ផ្សារ — 'market' in Khmer) digitizes that relationship into one platform both sides can trust.

Approach

H-Phsar digitizes wholesale ordering between Cambodian distributors and retailers. Each role gets a focused API for store management, purchasing, fulfillment, reporting, and notifications.

What I Built

Email OTP verification and JWT-secured sessions
Distributor catalog, inventory, and store management
Retailer carts, ordering, tracking, ratings, and bookmarks
Explicit order transitions with real-time WebSocket notifications

Implementation

Spring Boot 3.2 and Java 17 with MyBatis, PostgreSQL, Flyway, Spring Security, WebSocket, and OpenAPI. Role-scoped controllers and queries keep distributor and retailer workflows separate.

Architecture Flow

Spring Security + JWT

Spring Boot 3 REST API

MyBatis mappers

PostgreSQL + Flyway

WebSocket notifications

Every domain is split by role: distributors and retailers get separate controllers, services, and notification tables over one shared schema of 24+ tables. Orders move through an explicit status-driven state machine, so an order can never skip a step or be acted on by the wrong side of the marketplace.

Backend Evidence

Core data

tb_distributor_accounttb_retailer_accounttb_storetb_producttb_categorytb_ordertb_order_detailtb_status

Key endpoints

POST/authorization
Sign up, log in, and password reset flows
POST/authorization/api/v1/otp
Generate and email a 4-digit OTP to verify an account
POST/api/v1/retailer/orders
Add to cart, save drafts, and confirm a cart as a live order
GET/api/v1/distributor/reports
Order activity reports by month and year

Integration test

A PostgreSQL integration test runs accept and reject operations concurrently for the same pending order and checks that exactly one succeeds.

View integration test

Engineering Decisions

Challenge
Modeling two user roles without duplicating marketplace logic
Decision
Separated role-specific APIs over one shared relational model
Challenge
Preventing invalid or out-of-order order status changes
Decision
Enforced every order transition through an explicit state machine

Takeaways

An explicit state machine turns business rules into something you can read, test, and audit
Designing the API per role keeps permissions simple — the URL already says who may call it

Next Project

AuthHub — Reusable Authentication Service