Skip to content

Home

Jump to bottom
Terrence Daniels edited this page Aug 14, 2026 · 5 revisions

saga-full

A from-scratch demonstration of the Distributed Saga pattern: coordinating a long-running business transaction — order placement, payment settlement, fulfillment — across independent microservices, each owned by its own service and its own database, with no shared database transaction tying them together.

This is an original implementation, not a fork of any existing project. The module boundaries and general shape of the problem (order → payment → restaurant, with compensation on failure) are common territory for this class of system; the code, decisions, and tradeoffs recorded across this wiki are this repo's own. See the repo README for the top-level framing and the portfolio case study for a narrative write-up.

This wiki is a browsable reference layer on top of the repo's own docs (docs/architecture.md, docs/code-review.md, todo.md). It reorganizes that material by topic; for exact dates, phase numbers, and the full decision-by-decision log, the in-repo docs remain the source of truth.

Modules

All six planned backend modules are built and passing their test suites.

Module Role Page
user-contract Shared gRPC contract (user.proto) — Login + ValidateToken User-Contract
user-service Identity + auth: password login, JWT issuance/validation User-Service
order-service Saga entry point: order creation, transactional outbox, the order's PENDING → SUCCESS/CANCELLED lifecycle Order-Service
payment-service Charges on order creation, refunds/compensates on restaurant rejection Payment-Service
restaurant-service Inventory allocation + fulfillment decision (the saga's approve/reject step) Restaurant-Service
api-gateway-service Reactive edge: JWT-guarded routing, gRPC-backed login, circuit breaker on the downstream hop API-Gateway-Service

Start here

  • Saga Flow — how a single order actually moves through all six services, including compensation.
  • Architecture Overview — the tech stack and the decisions that shaped it (Gradle over Maven, io.github.terrence721.saga namespace, real bugs found along the way).
  • Getting Started — build, run, and stand up the local Postgres/Kafka stack.
  • Testing Strategy — how each layer is tested, and the JDK-25-vs-tooling gotchas that shaped it.
  • Code Review Audit — the file-by-file review this repo is currently mid-way through.

Elsewhere

Clone this wiki locally