EasyDora

Overview

EasyDora is a microservices-based e-commerce platform. It demonstrates how to build an end-to-end distributed business flow. It uses event-driven architecture, RabbitMQ, the Outbox Pattern, contract testing, and continuous integration.

Each service uses the language and stack suited to its workload, not the stack chosen for convenience. Go handles performance-sensitive gateway and inventory paths. Spring Boot handles domain-rich business logic. FastAPI handles async notification processing.

Status: in active development. All eight services are implemented and building: api-gateway, auth, products, inventory, orders, billing, notification, frontend. All six messaging services (auth-service, products-service, orders-service, billing-service, inventory-service, notification-service) have contract tests. These tests validate each service's event/message DTOs against JSON Schemas shared in /schemas/json/. The tests cover all 17 currently-published messages (see ADR-0002's 2026-07-13 Update). notification-service consumes both order.created and order.status-changed via RabbitMQ. It enriches order.created with a real HTTP call to auth-service. It persists an observable notification per event, and never overwrites a previous one. You can query these notifications via its own read-only GET /notifications/{orderId}. No real email/SMS provider exists yet (see ADR-0014). A SvelteKit frontend now exists as a thin, read-mostly client over the API Gateway. It covers login, catalog browsing, checkout, order tracking, and a notification/observability view. It is deliberately not a full storefront (see ADR-0026). See Service Status for the current breakdown.

What This Project Demonstrates

Event-driven architecture on RabbitMQ — every cross-service interaction (user lifecycle, product catalog, order/stock/payment/ notification) flows through topic exchanges. No domain service calls another synchronously. See Architecture and ADR-0007.
Outbox Pattern — auth-service, inventory-service, orders-service, and billing-service each write their outbound events in the same database transaction as the state change that triggers them. This way, an event is never silently lost on a crash between commit and publish. See ADR-0003, ADR-0007, and ADR-0037 for the consolidated specification and its extension to orders-service and billing-service.
Contract testing — event/message DTOs are validated against versioned JSON Schemas. This catches producer/consumer drift automatically, instead of in production. See ADR-0002.
Cross-service JWT broadcast authentication — auth-service issues the token once. Every other service builds its own in-memory cache from a broadcast event, instead of re-verifying signatures locally. See the Overview's Communication section.
Circuit breaker at the API Gateway — outbound proxy calls fail fast instead of piling up when a downstream service is down. See ADR-0006 and ADR-0009.
Transparent Gateway routing — the Gateway forwards every request's path unchanged. It never rewrites a service's contract. Every service is self-namespaced under its own Gateway segment (/auth, /products, /orders, /billing, /inventory). A direct call and a call proxied through the Gateway hit the exact same path. See ADR-0025.
Three-phase CI: unit tests with no infrastructure (Phase 1), integration tests against real Postgres/RabbitMQ service containers (Phase 2), and cross-service end-to-end tests driven through public HTTP APIs against real running processes (Phase 3). See ADR-0012 and ADR-0013.
A polyglot stack matched to workload, not convenience — Go, Spring Boot, and FastAPI each do the job they are best suited for. See Design notes.
A fully reproducible, real-command business flow — signup through order, stock reservation, payment, and notification. This flow is documented and validated against real containers. See the walkthrough and sequence diagram.
Distributed tracing, two complementary mechanisms — a CorrelationId is born at the first HTTP request, or reused from the client. It rides every hop's HTTP headers and native AMQP message properties unchanged, letting you follow one business operation through every service's logs with a single grep, in three languages. Alongside it, every service also exports OpenTelemetry spans to a Jaeger backend, giving a visual span tree and real per-hop latency across HTTP and RabbitMQ hops, in the same three languages. See docs/architecture/observability.md and ADR-0024 (including its 2026-08-02 Update).
A thin-client frontend, not a parallel architecture — the SvelteKit UI has no business logic of its own. It calls the Gateway exclusively. It surfaces the backend's own tracing identifiers, instead of inventing a client-side observability layer. See ADR-0026.

Quick Start

Prerequisites: Docker Desktop (Windows/Mac) or Docker Engine (Linux), Docker Compose, Git.

docker --version
docker-compose --version

git clone <repo-url>
cd easydora

# Start all implemented services
docker-compose up -d

# Check status
docker-compose ps

All eight services (API Gateway, Auth, Products, Inventory, Orders, Billing, Notification, Frontend) come up and respond on their ports. See Service Status for the full port list. Open http://localhost:3000 for the frontend once docker-compose ps shows everything healthy.

docs/walkthrough.md has a full, reproducible business-flow walkthrough: signup → product → order → stock reservation → payment → notification. It runs entirely through curl against each service's public API, with real request/response examples. docs/sequence-diagram.md shows the same flow as a Mermaid sequence diagram. If Docker Compose fails to connect on Windows, see docs/TROUBLESHOOTING.md.

Running on Kubernetes (kind)

Docker Compose remains the recommended way to run EasyDora locally. As a parallel, optional alternative, the backend and observability stack can also run on a local kind cluster. See ADR-0040 for why, and k8s/README.md for the full, step-by-step guide:

kind create cluster --config k8s/kind-config.yaml
# build + kind load docker-image each service (see k8s/README.md)
kubectl apply -f k8s/base/secrets.yaml   # copy from secrets.example.yaml first
kubectl kustomize k8s/base --load-restrictor LoadRestrictionsNone | kubectl apply -f -

Fast local dev loop (`docker compose watch`)

The default docker compose up above builds each service's full multi-stage production image — the right choice for validating a release, but slow to repeat after every single-line code change (a full Maven recompile plus repackage per Spring Boot service, in particular). For an active debugging session, run instead:

docker compose -f docker-compose.yml -f docker-compose.watch.yml up --watch

This builds each service's dev Dockerfile stage (full toolchain + already-downloaded dependencies, kept in the image) instead of the production one, then syncs changed source files into the already-running container — recompiling or hot-reloading only what changed, instead of rebuilding the image. Editing a dependency manifest (pom.xml, go.mod/go.sum, package.json) or the shared correlation-commons/ correlation-commons-go libraries still falls back to a full rebuild of just that service, triggered automatically. See ADR-0042 for the full design and the trade-offs of this second, dev-only image per service.

Architecture

See the Architecture Overview for the full breakdown: bounded contexts, business flows, communication, persistence, and the exchange/event table. The diagram below shows just the component topology, at a glance:

                    ┌─────────────┐
                    │ API Gateway │  Go + Gin
                    └──────┬──────┘
                           │
        ┌──────────┬───────┴───────┬──────────┐
        │           │               │          │
   ┌────▼───┐  ┌────▼─────┐   ┌────▼────┐ ┌────▼─────┐
   │  Auth   │  │ Products │   │ Orders  │ │Inventory │
   │ Spring  │  │ Spring + │   │Spring + │ │  Go +    │
   │  Boot   │  │ Postgres │   │RabbitMQ │ │ Postgres │
   └─────────┘  └──────────┘   └────┬────┘ └──────────┘
                                     │
                          ┌──────────┴──────────┐
                          │                      │
                    ┌─────▼─────┐         ┌──────▼──────┐
                    │  Billing  │         │Notification │
                    │  Spring   │         │  FastAPI +  │
                    │  Boot     │         │  RabbitMQ   │
                    └───────────┘         └─────────────┘

Frontend (SvelteKit, thin client) consumes the API Gateway only.

Documentation

Architecture Overview — the map: bounded contexts, business flows, communication, persistence, and the exchange/event table.
Architecture Decision Records — 42 ADRs, one per architectural decision made along the way, in chronological order.
Observability — how one business operation is traced end to end through every service's logs, via a propagated CorrelationId, without a tracing backend.
Postman collection — the same main flow as an importable, runnable collection, with automatic ID/token capture. It complements the walkthrough.
Architectural Principles — the recurring principles behind those decisions. These principles were extracted from the ADRs, not declared up front.
End-to-end walkthrough — the full business flow, driven entirely by curl, with real requests/responses from an actual run.
Sequence diagram — the same flow as a Mermaid diagram.
Design notes — why each service uses the stack it uses.
Service Status — per-service ports, stack, and test coverage.
Versioning and Release Policy — what a version number means here, and what must stay in sync at release time. This is project governance, not architecture. It is kept separate from the ADRs above on purpose.

Service Status

Service	Stack	Port	Status	Test Coverage
API Gateway	Go + Gin	8080	Implemented	9 test functions — circuit breaker (ADR-0006/ADR-0009), correlation middleware (ADR-0024), and transparent routing across all 6 services (ADR-0025)
Auth	Spring Boot + PostgreSQL + JWT + Outbox	8081	Implemented	29 tests — unit + `*IT` (Outbox, real Postgres/RabbitMQ), including 3 contract tests covering `user.registered`/`user.verified`/`jwt.created` (ADR-0002), a Progress Watchdog backing its `/health/liveness` signal, and a `ConnectionListener`-based reconnection-metrics test (ADR-0038's 2026-07-20 Update)
Products	Spring Boot + PostgreSQL + RabbitMQ	8082	Implemented	32 unit tests, including 6 contract tests covering `product.created`/`product.updated`/`product.deleted`/`user.verified`/`jwt.created` (ADR-0002), a Progress Watchdog backing its `/health/liveness` signal, and a `ConnectionListener`-based reconnection-metrics test (ADR-0038's 2026-07-20 Update)
Inventory	Go + PostgreSQL + RabbitMQ + Outbox	8083	Implemented	35 tests — 26 unit + 9 integration (real Postgres/RabbitMQ, includes concurrency via `go test -race`), including 7 contract tests covering `product.`/`stock.` (ADR-0002), a `NotifyClose`-based reconnect supervisor that redeclares topology after every reconnect, and publisher-confirms in the Outbox publisher (both proven against a real broker restart, ADR-0038's 2026-07-20 Update)
Orders	Spring Boot + PostgreSQL + RabbitMQ + Outbox	8084	Implemented	112 tests — unit + `*IT` (real Postgres/RabbitMQ), including 4 covering self-purchase prevention, 31 covering the order fulfillment lifecycle (ship/deliver, single-source-of-truth transitions, the `previousState` fix), 6 covering optimistic locking on `Order`, 23 covering the payment compensation saga (ADR-0034), Outbox coverage for all four publishes (ADR-0037), 13 contract tests (ADR-0002), a Progress Watchdog backing its `/health/liveness` signal, and a `ConnectionListener`-based reconnection-metrics test (ADR-0038's 2026-07-20 Update)
Billing	Spring Boot + PostgreSQL + RabbitMQ + JWT + Outbox	8085	Implemented	60 tests — unit + `*IT` (real Postgres/RabbitMQ), including 6 covering the deterministic payment provider and its single-creation-path guarantee, 4 covering optimistic locking on `Payment`, 7 covering the payment compensation saga (ADR-0034), Outbox coverage for all four publishes (ADR-0037), 6 contract tests (ADR-0002), a Progress Watchdog backing its `/health/liveness` signal, and a `ConnectionListener`-based reconnection-metrics test (ADR-0038's 2026-07-20 Update)
Notification	FastAPI + PostgreSQL + RabbitMQ	8086	Implemented	64 tests — 55 unit + 9 integration (real Postgres/RabbitMQ/auth-service), including 6 contract tests covering `order.created`/`order.status-changed`/`jwt.created` (ADR-0002) and an explicit heartbeat + Progress Watchdog proven to resume consuming after a real broker-forced disconnect, now also exposing the same reconnection metrics as every other service (ADR-0038's 2026-07-20 Update)
Frontend	SvelteKit + TypeScript	3000	Implemented	0 automated tests — validated manually end to end (see ADR-0026)

"Implemented" means the service builds, runs, and has the test coverage shown above. It does not mean every known gap is closed. See the Roadmap below and each ADR's Consequences section for what's still open.

Event contracts are validated via JSON Schema for all 17 currently-published messages. See ADR-0002 for what this covers, and for the known price type gap schema validation can't catch. A separate audit covered the messaging layer's wiring bugs: routing keys, field names, a competing-consumer incident. See ADR-0001.

billing-service's mvn verify suite needed three real bug fixes the first time it ran against Postgres/RabbitMQ. One bug was a TYPE_MAPPINGS entry pointing at another service's event class. This bug is a concrete instance of this project's lack of contract testing between services, since each service hand-duplicates its own copy of shared event DTOs. See ADR-0008.

inventory-service's stock-reservation idempotency uses redelivery-safe caching and per-OrderID locking for genuine concurrency. A residual gap remains once a cache entry expires. ADR-0007 and the service's own source document this; this README does not repeat it.

Infrastructure: RabbitMQ Management (15672), PostgreSQL (5432), Prometheus (9090), Grafana (3001, see ADR-0036).

Design notes

The stack split is deliberate:

Go (Gateway, Inventory) — performance-sensitive, high-throughput paths.
Spring Boot (Auth, Products, Orders, Billing) — domain-rich business logic, where Java's ecosystem (validation, transactions, ORM) pays off.
FastAPI (Notification) — async I/O-bound processing. It currently runs a synchronous RabbitMQ consumer plus an HTTP client. See ADR-0014 for why the project chose sync over aio-pika/asyncpg at this size.
SvelteKit (Frontend) — lightweight reactive UI.

Architecture Decision Records

ADR	Title	Status	Summary
0001	Messaging wiring audit	Accepted, updated 2026-07-08	Fixed five routing/field-name/listener bugs (RabbitMQ and Kafka). Fixed one JWT-queue message-loss incident dated back to the project's first commit. Removed one dead payment-event code path. `OrderStatusChangedEvent`'s designated consumer (notification-service) is now implemented. See the Roadmap.
0002	JSON Schema contract testing	Accepted	Adopted JSON Schema (draft 2020-12) for event contracts, versioned in `/schemas/json/`. Fixed two catalogued DTO drifts. Documented the `price` type drift (BigDecimal vs float64) as a known gap schema validation cannot catch. Its 2026-07-13 Update extends coverage from 2 to all 17 currently-published messages (fact-events and commands alike) across all six services. It fixes a real drift found along the way (`JwtCreatedEvent.userId`). It makes a schema-plus-contract-test mandatory for every new event from now on. See CONTRIBUTING.md.
0003	Outbox pattern for auth-service	Accepted	Fixed `verifyEmail`'s publish-before-save ordering with a polled `outbox_events` table. Closed `inventory-service`'s equivalent risk (Go) the same way, as part of ADR-0007's RabbitMQ migration. Found and resolved a Flyway/Hibernate schema-duplication bug along the way, in ADR-0004.
0004	auth-service schema authority fix	Accepted, extended by ADR-0011	Fixes the schema duplication found in ADR-0003. `V1`/`V2` created tables in `public`, while Hibernate's `ddl-auto=update` silently created the real, actually-used copies in `auth_schema`. A `V3` migration recreates both tables in `auth_schema`, matching Hibernate's live schema exactly. `ddl-auto` is locked to `validate`. Left checking the other three services as explicit future work. See ADR-0011.
0005	Secret rotation and removal of hardcoded credentials	Accepted	Rotated three credentials hardcoded in `docker-compose.yml` since the project's first commit (public repo), for real, against the live Postgres/RabbitMQ. Replaced them with `${VAR}`/`.env`. Removed orphaned JWT config from three services that never consumed it. History was not rewritten; old values are treated as permanently compromised.
0006	Circuit breaker in the API Gateway	Accepted	Added `sony/gobreaker`, one breaker per service (`auth`, `products`, `inventory`, `orders`; billing excluded, see ADR-0009). 5 consecutive failures open the breaker; the cooldown is 30s. Verified against real containers: stopping inventory-service made it fail fast, while the other three kept responding normally.
0007	Remove Kafka broker (migrate to RabbitMQ)	Accepted, implemented	Removed Kafka from every service. Moved product./stock./order.* events over to RabbitMQ topic exchanges. inventory-service's stock reservation outcome is now written through an Outbox table (see ADR-0003), instead of a direct post-commit publish.
0008	Separate unit and integration tests via Surefire/Failsafe	Accepted, partially superseded	Originally: renamed four test classes touching real Postgres/RabbitMQ to the `IT` suffix, and moved them to `maven-failsafe-plugin`, across all four Spring services. Since updated (see the ADR's 2026-07-06 addendum): a later step of ADR-0007's Kafka-to-RabbitMQ migration replaced three of those four `IT` classes with broker-agnostic behavior tests. Only billing-service's `BillingServiceApplicationIT` remains. `maven-failsafe-plugin` was removed from the other three services' `pom.xml`.
0009	Extend the API Gateway circuit breaker to billing-service	Accepted	Same structure as ADR-0006 (`sony/gobreaker`, 5 failures / 30s cooldown), applied to the one remaining entry left on the plain proxy. Closes ADR-0006's open Roadmap item.
0010	Uniform health checks across all six services	Accepted	Every Docker `HEALTHCHECK` now targets each service's own unauthenticated `/health` endpoint, instead of `/actuator/health`. billing-service gained a `HealthController`/`SecurityConfig`. orders-service's broken `docker-compose.yml` override was removed. auth-service/inventory-service/api-gateway gained a `HEALTHCHECK` they never had. All six services verified `healthy` simultaneously for the first time.
0011	Flyway as the single schema authority in every Spring Boot service	Accepted	Closes the gap ADR-0004 explicitly left open. `flyway-core` was silently missing from products-service and billing-service's `pom.xml`. This made their Flyway config dead, and let `ddl-auto=update` author their entire live schema, with visible drift from what the migrations specify. billing-service gets its first real migration. All four services now baseline correctly and run with `ddl-auto=validate` everywhere.
0012	CI Phase 2 — real-infrastructure integration tests via service containers	Accepted	Added a new `integration` job in CI: a matrix of auth-service/orders-service/billing-service/inventory-service, each against its own fresh Postgres/RabbitMQ service-container pair. Restores three previously-removed `*IT` classes and adds new ones. Every hop is tested from at most one side, producer or consumer, never both, and never across a real process boundary. See ADR-0013.
0013	CI Phase 3 — cross-service end-to-end tests via real running processes	Accepted	Two named jobs start multiple real services as actual processes against one shared Postgres/RabbitMQ pair. Both drive flows through public HTTP APIs only: `catalog-onboarding` (auth/products/inventory) and `order-lifecycle` (auth/orders/inventory/billing). This work surfaced and fixed a real bug: billing-service's Basic Auth never actually worked (403 regardless of credentials).
0014	Notification Service — first Python/FastAPI service	Accepted	Consumes `order.created` via a new RabbitMQ queue. Enriches it via a real HTTP call to a new minimal auth-service endpoint (`GET /users/{id}/notification-profile`). Persists an observable notification in a new `notification_schema`. No real email/SMS provider exists; one `FakeNotificationSender` implementation stands in. Found, but did not fix, the same missing-`.httpBasic()` defect class ADR-0013 fixed in billing-service, this time in auth-service — currently latent.
0015	billing-service joins the JWT broadcast pattern; auth-service's latent `.httpBasic()` gap fixed	Accepted, updated 2026-07-07	auth-service originally got the same one-line `.httpBasic()` fix ADR-0013 applied to billing-service. Later this was simplified further to `denyAll()`, once it was clear no endpoint depended on any auth mechanism (see the ADR's Update). billing-service was the only service protected solely by Spring Boot's default Basic Auth. It now authenticates via the same Bearer JWT broadcast cache already used by products-service and orders-service (auth-service is the producer of that broadcast, not a consumer of it). New `JwtConsumerBehaviorTest`/`PaymentControllerSecurityTest`/`BillingJwtCreatedWiringIT` give this mechanism real regression coverage for the first time.
0016	Shared Maven parent POM for the four Spring Boot services	Accepted	A new root `pom.xml` (inheritance only, no reactor) standardizes all four services on Spring Boot 3.2.12, previously split 3.2.0/3.2.12. It centralizes every dependency/plugin that was identical across all four by hand. This required changing Docker's build context to the repository root for all four services, so the parent resolves inside each build.
0017	notification-service survives a slow/restarting RabbitMQ and Postgres	Accepted	Found while validating the end-to-end walkthrough against a real, freshly-started stack: the RabbitMQ consumer thread made exactly one connection attempt, and died silently on a real startup race. This left the container "healthy" but permanently unable to process any event. Both the RabbitMQ consumer and the Postgres schema-init step now retry, instead of giving up.
0018	Persistence strategy — shared PostgreSQL instance, schema-per-service ownership	Accepted	Formally registers a decision that was implicit since the project's first commit: one Postgres instance, one schema per service, ownership enforced by convention rather than by database ACLs. Argues the architectural boundary is data ownership, not the physical instance. Every property this project demonstrates already holds without database-per-service.
0019	Uniform message consumption resilience (limited retry, exponential backoff, dead-lettering)	Accepted	`products-service`, `orders-service`, and `billing-service` now share the same native Spring Boot listener retry policy: 3 attempts, exponential backoff, and a dead-letter exchange/queue per service. Eight listener methods that previously swallowed exceptions internally were fixed to propagate them, so container-level retry/DLQ actually applies to business-logic failures, not just malformed messages. `auth-service` has no consumer at all, so is out of scope. `notification-service` (Python) keeps its separate, unrelated gap.
0020	Complete the notification domain — consume `order.status-changed`, add a read-only API	Accepted	`notification-service` now consumes `order.status-changed` in addition to `order.created`. It reuses the prior notification's enriched user info instead of a second synchronous call, since the event carries no `userId`. It adds a read-only `GET /notifications/{orderId}`, closing the walkthrough's one direct-Postgres-access step. Found, but did not fix: `billing-service` never publishes a payment outcome event, so `order.status-changed` is never emitted for a payment transition.
0021	Payment outcome integration — billing-service publishes `payment.approved`/`payment.failed`, orders-service reacts	Accepted	Closes the gap ADR-0020 found. `billing-service` now publishes a payment outcome event once `PaymentService.processPayment` resolves it. A new `PaymentEventsConsumer` in `orders-service` finally calls `OrderService.handlePaymentReceived`/`handlePaymentFailed`, previously unreachable since ADR-0001 removed their incorrectly-typed predecessor. Also fixed a latent bug those methods had: `previousState` was hardcoded to `PENDING` instead of the order's real prior state, found by the first tests that ever exercised them. `notification-service` required no changes.
0022	notification-service consumption resilience (retry, backoff, dead-lettering)	Accepted	Closes notification-service's last remaining gap from ADR-0019/ADR-0017. Its `pika` consumer used to ack even on failure, silently dropping malformed or unexpected-error messages. It now retries up to 3 times with exponential backoff, using a RabbitMQ retry queue with a per-message TTL, not a sleep or poll, before dead-lettering. This matches the same numbers and conceptual behavior as the Spring services, built on different primitives, since Pika has no retry-template equivalent. Found, and since fixed (see ADR-0022's Update): `products-service`'s `handleUserVerified` had no role filter, so every buyer's `user.verified` event was dead-lettered. A second, 2026-08-03 Update adds `notification_retry_total{outcome}`, a Prometheus counter, so a retry or terminal dead-lettering is no longer visible only in this file's own log lines.
0023	Notification Service Persistence Evolution Strategy	Accepted	Formally reviews and closes the "no Alembic" gap left open since ADR-0014. `scripts/init.sql` has not changed once across four ADRs of functional growth. A comparison against `inventory-service`, whose own idempotent init.sql has evolved twice, safely, with no versioned tool, shows the current approach has headroom beyond what notification-service has needed. Keeps the idempotent script. Documents concrete criteria for reopening the decision if the schema outgrows it.
0024	Distributed tracing via propagated correlation identifiers, not a tracing backend	Accepted	CorrelationId/RequestId/MessageId propagate through HTTP headers and native AMQP message properties, not a new wire format. All seven services log them in a consistent structured format. Two small shared modules exist: `correlation-commons` for the four Spring services, `correlation-commons-go` for the two Go services. This is a deliberate, narrow exception to this project's "no shared library" convention, since this code has no business meaning and must stay identical to hold the CorrelationId contract. Found and fixed two real bugs: notification-service's retry path silently dropped correlation/message ids, and the Go shared module's logger had a service name hardcoded from before it had a second consumer. See docs/architecture/observability.md for the full design. A 2026-08-02 Update adopts OpenTelemetry and a Jaeger backend alongside this design, not instead of it: every service now also exports spans, with a real login producing a single trace spanning 6 services and 13 spans across three languages. Outbox-mediated publishes (orders-service, inventory-service, billing-service) don't yet carry a trace across their write-to-publish gap — a documented, not-yet-closed residual gap, unlike CorrelationId's own envelope trick for the same gap. A 2026-08-03 Update closes it: the envelope (Java's `OutboxEnvelope`/Go's `outboxEnvelope`) gained a `traceparent` field, captured at write time and restored as the publish call's producer span parent. `auth-service` gets the same fix for free via the shared `correlation-commons` codec, even though the Roadmap item only named the other three. A first version, built on raw OpenTelemetry API, passed every unit test but was caught by live validation against a real Jaeger trace: every outbox publish's own chain was internally connected, but never linked back to the original HTTP request, since Spring AMQP's Observation-based instrumentation consults Micrometer's own current-span tracking, not OTel's raw `Context.current()`. Corrected to build on Micrometer Tracing's own `Tracer`/`Propagator` instead — the same abstractions the instrumentation itself reads.
0025	Gateway transparent routing — every service is self-namespaced	Accepted	Closes the `inventory-service` 404-through-the-gateway bug ADR-0024 found. The Gateway no longer strips any service prefix; it forwards the incoming path unchanged. `auth-service`/`products-service`/`orders-service`/`billing-service` each gained a `server.servlet.context-path` matching their own Gateway segment (`inventory-service` was already self-namespaced). Every direct caller of those four services (Dockerfile `HEALTHCHECK`s, CI readiness checks, `e2e-tests`, the Postman collection) was updated in lockstep. The Postman collection now has parallel `Via Gateway (primary)` and `Direct (debug)` folder trees.
0026	SvelteKit frontend as a thin client over the API Gateway	Accepted	A new `frontend/` (SvelteKit + TypeScript, SSR disabled, `adapter-node`) consumes only the Gateway. Building it surfaced and fixed four real defects no prior `curl`-based client could catch: CORS wired but shadowed by Spring Security in two services and entirely missing in four; `products-service`'s JWT filter terminating requests before `permitAll()` paths could ever be reached; its catalog endpoints unreachable by any buyer token by design; and the Gateway echoing `X-Correlation-Id`/`X-Request-Id` twice under one header. `notification-service` gains a Gateway route, closing the one gap ADR-0025 left open.
0027	JWT principal as the sole identity source for orders/products	Accepted	Closes a Critical Roadmap item. `orders-service`/`products-service` derived business identity from a client-supplied `X-User-Id` header, instead of the authenticated JWT principal. This let any valid token impersonate any other user by changing one header, confirmed live with a real two-buyer impersonation before the fix. Both controllers now derive identity exclusively from `@AuthenticationPrincipal`. `X-User-Id` no longer exists anywhere in either service's request path. Its 2026-07-10 Update extends the same pattern to `billing-service`'s `PaymentController`, all four endpoints, closing a separate High Roadmap item.
0028	notification-service authentication and ownership check	Accepted	Closes a High Roadmap item, a real IDOR: `GET /notifications/{orderId}` had no authentication at all. notification-service gains its own JWT broadcast cache, consuming `jwt.created` for the first time, the same pattern as every Spring service's `JwtConsumer`. It now requires the caller to be the order's own buyer, read from that order's real `order.created` payload, or 403 otherwise. Confirmed live with a real two-buyer test.
0029	Activating the order fulfillment lifecycle (ship/deliver)	Accepted	Closes a Medium Roadmap item. `SHIPPED`/`DELIVERED` were configured state machine transitions with no code path to reach them. Adds `POST /{orderId}/ship`, the project's first role-gated, not ownership-gated, endpoint, using the new `ADMIN` platform-operations role. Adds `POST /{orderId}/deliver`, ownership-gated like `cancelOrder`. Replaces `canCancel()`'s hand-written eligibility list with a single `isTransitionAllowed` derived from the state machine's own configured graph. Closes a self-registration-as-admin path in auth-service's `/signup`. Live validation caught and fixed a real `previousState`-after-mutation bug in `cancelOrder` and both new methods. No new event type, no new table.
0030	Deterministic payment provider	Accepted	Closes a Medium Roadmap item. `billing-service`'s `PaymentProvider`/`PaymentMockService` abstraction was dead code; `PaymentService.processPayment` decided approval with `Math.random() < 0.9` directly instead. `PaymentService` now depends exclusively on `PaymentProvider`. The fake's existing amount-parity rule, kept rather than replaced with a hash, makes the same order always resolve the same way. Also removed a second, unused `PaymentResult` class sharing `PaymentService`'s package, a real name-collision risk once the real one got imported. `docs/walkthrough.md`/`docs/sequence-diagram.md`/`postman/README.md` no longer hedge with "either outcome".
0031	Single source of truth for payment creation	Accepted	Closes a Low Roadmap item. `PaymentService.processPayment` had an "API fallback" branch that created a new `Payment` on the spot when none existed, and it never set `userId`. Investigation found no legitimate caller ever exercised it; the frontend, walkthrough, and Postman collection always process an order that already went through `order.created`. Removed the fallback, and the dead `amount` parameter it alone used, instead of patching the bug. A missing `Payment` is now a `404` domain error via a new `PaymentNotFoundException`. Also removed `POST /api/payments/pending`, an already-dead second alias for `/process`.
0032	Accept the hybrid Spring State Machine pattern in orders-service	Accepted	Closes an Architectural-note Roadmap item without changing code. Investigated making the state machine a live authority (low value: no guards/extended state, single replica), and dropping the framework for a plain transition table (low risk, but no functional gain). Decided the migration cost of either outweighs a benefit that resolves no active bug. Also opens a new, unrelated Low Roadmap item found along the way: `Order` has no `@Version` column, so concurrent writes from multiple RabbitMQ consumers and HTTP endpoints have no conflict detection.
0033	Optimistic locking on Order and Payment	Accepted	Closes the `@Version` Low Roadmap item ADR-0032 opened. Adds `@Version` to `Order` and `Payment` only, not `Product`/`User`, which have no real concurrent-writer path. Backs it with `saveAndFlush` at the point each transition is persisted, so a conflict is never discovered after its event already published. Adds a `409 Conflict` mapping in both services. Documents evaluating and rejecting pessimistic locking for this domain's current low-contention, event-driven shape, with explicit criteria for revisiting that later.
0034	Payment compensation saga for approved-but-unfulfillable orders	Accepted	Closes a Medium Roadmap item. A `payment.approved` arriving for an order already `INVENTORY_FAILED`/`CANCELLED` was silently swallowed, leaving `Payment` wrongly `APPROVED` with nothing to refund it. Evaluated and rejected synchronous compensation, immediate reversion, and Saga Orchestrated. Adopted a choreographed saga consistent with the rest of the domain instead: Orders publishes a `RefundPaymentCommand`, a command not a fact-event, after reactivating the pre-existing, never-wired `REFUNDING`/`INITIATE_REFUND`/`REFUND_COMPLETED`. Billing alone decides and owns `Payment`, publishing `payment.refunded`/`payment.refund.failed` back. No `REFUND_PENDING`, no refund-specific transaction id; each was deliberately rejected and documented, not omitted by oversight. Outbox was also deliberately not adopted for the new publish alone, to avoid an asymmetry with this service's other best-effort publishes. A 2026-07-15 Update closes that gap, once a broader analysis extended Outbox to all four of `orders-service`'s publishes together (see ADR-0037).
0035	Reject DTO code generation from JSON Schema, at the project's current scale	Accepted	Closes a Low Roadmap item by decision, not implementation. Measured every schema's real git history (one content-change each, ever) and the one real DTO drift ever found, already caught by its own contract test. Concluded that `jsonschema2pojo`/`go-jsonschema`/`datamodel-code-generator` would cost three new build toolchains and the intentional-partial-consumer DTO pattern already in deliberate use, for a drift rate of one occurrence. This is a cost/benefit conclusion, not a rejection of the technique. Documents explicit, measurable criteria (event count, schema churn, a second missed drift, partial-consumer DTOs becoming the exception) that would reopen it.
0036	Quantitative observability via Prometheus and Grafana	Accepted	Narrows ADR-0024's bundled rejection of Prometheus/Grafana; that cost analysis targeted a full tracing backend, which these two don't actually need. Adopts them for the aggregate questions CorrelationId logging was never meant to answer: error rate, latency, queue depth, business volume. RabbitMQ's own `rabbitmq_prometheus` plugin and each Spring service's HikariCP pool cover RabbitMQ and Postgres connection visibility, with zero new exporter containers. The two Go services needed one small custom HTTP-metrics middleware, since `promhttp` alone, unlike Micrometer, doesn't auto-instrument request rate/latency. Five deliberately-scoped business counters, dashboards provisioned as code. No Alertmanager, no Loki, no per-event metric spam. ADR-0024's rejection of a full tracing backend (OpenTelemetry/Jaeger/Zipkin) stays unchanged. A 2026-07-15 Update adds a sixth counter, `inventory_idempotent_duplicate_detected_total{operation}`, answering a different kind of question than the original five: whether a known, accepted residual risk, duplicate command delivery caught by `inventory-service`'s idempotency cache, is actually happening at runtime, not just theoretically possible. A second 2026-07-15 Update adds a seventh, `jwt_cache_lookup_total{outcome}` (hit/miss/expired) in all four broadcast-JWT-cache services, landed together with ADR-0039's TTL implementation.
0037	Consolidated Outbox Pattern specification	Accepted	auth-service's (ADR-0003) and inventory-service's (an aside inside ADR-0007, never its own ADR) Outbox implementations agreed on everything structural, but had never been specified as one concern. They drifted where nothing pinned them down: neither had a metric on the publisher itself, and logging was inconsistent in opposite directions between the two languages. Harmonizes both: structured, correlated logging on every path, and two new metrics, `outbox_events_published_total`/`outbox_publish_lag_seconds`, following ADR-0036's convention. Adopts an explicit adoption criterion for future decisions about extending Outbox elsewhere: impact of loss on a cross-service business process, not caller observability or an unrelated retry mechanism. Did not itself extend Outbox to any new service at the time. Two 2026-07-15 Updates close the `orders-service` Roadmap item ADR-0034 opened and the `billing-service` gap, extending Outbox to all four publishes of each service. Every publish in the system that qualifies under this ADR's own criterion now has it. A third 2026-07-15 Update formalizes an outbox retention policy, no automated cleanup, with explicit criteria for revisiting, and explicitly rejects CDC/Debezium in favor of the existing 5-second poll.
0038	Infrastructure startup resilience	Accepted, updated 2026-08-03	`orders-service` crashed on boot when RabbitMQ's Erlang node answered its own healthcheck before its AMQP listener accepted connections, the same class of bug ADR-0017 claimed the four Spring services were already immune to. Verified live instead of trusting that claim: confirmed both a listener-less and a listener-bearing Spring service already tolerate this race via Spring Boot's own autoconfigured `SimpleMessageListenerContainer`. The actual cause was `orders-service`'s own redundant, imperative `RabbitMQInitializer`, since deleted. The same investigation found and closed a second, unrelated, more severe gap, live-tested the same way: all four Spring services crashed immediately with zero retry if Postgres was slow instead of RabbitMQ, fixed with `spring.datasource.hikari.initialization-fail-timeout=30000` per service. `inventory-service`'s own Postgres connection gained the same bounded retry its RabbitMQ connection already had, closing an internal asymmetry within that one service. Its 2026-07-17 Update tackled the neighboring, previously-untested question: what happens when an already-connected client's broker restarts mid-run, as `kind`'s no-PersistentVolume RabbitMQ (ADR-0040) does on every pod restart. Verified live that Java's automatic connection/topology recovery already handles it. Closed the one gap that Update believed it had found, `inventory-service`'s Go client never subscribed to `NotifyClose`, with a reconnect supervisor. Gave `notification-service`'s `pika` consumer an explicit heartbeat, and added a Progress Watchdog to all six services. Its 2026-07-20 Update found that supervisor's own validation had a gap: it only tested the TCP connection dying, never the exchange itself disappearing, the actual Kubernetes failure mode. Re-testing against real topology loss found the Go supervisor reconnected the socket but never redeclared `order.exchange`/`product.exchange`, leaving every consumer's `QueueBind` failing forever. Fixed, and proven this time by deleting the exchange itself, not just closing the connection. The same fix surfaced two more real bugs in the same file: the Outbox publisher's fire-and-forget `Publish` could silently mark an event "published" that the broker never actually accepted, and a single permanently-bad outbox row could poison an entire poll batch's channel. Both closed with publisher confirms and per-event channel validation. `orders-service`/`billing-service`'s JWT filters were standardized to match `products-service`'s already-correct behavior. A reconnection observability contract, auto-reconnect, redeclare topology, progress-based liveness, is now stated explicitly. New `rabbitmq_reconnect_attempts_total`/`rabbitmq_topology_setup_total{outcome}`/`messaging_last_progress_timestamp_seconds` metrics apply across all six services. A new Grafana dashboard (`EasyDora / Resilience`) and a completed Postman collection cover the payment-compensation saga (ADR-0034) end to end. `restart: on-failure` was added on every `docker-compose.yml` service, so the same self-healing applies outside Kubernetes too. A 2026-08-03 Update closes a Low Roadmap item: the boot-race tolerance rested on a one-time human confirmation, never a test this project runs on every push. A new `boot-race` CI job (one per Spring service) starts the app with neither Postgres nor RabbitMQ reachable, confirms it survives instead of crashing, then starts both deliberately late and asserts recovery — no `services:` block, since that would start infra before the race it needs to reproduce. A second 2026-08-03 Update closes a related item: `notification-service`'s `run_consumer` bounded its own boot-time RabbitMQ connection (`BOOT_MAX_ATTEMPTS = 10`, matching `ensure_schema`'s Postgres bound and `inventory-service`'s own already-bounded boot connection), raising instead of retrying forever once exhausted. The steady-state reconnect path after a first successful connection stays unbounded, unchanged.
0039	Broadcast JWT cache — restart-recovery limitation and token-lifetime TTL	Accepted	Centralizes a limitation previously only mentioned as an aside inside ADR-0027 and ADR-0028, that a service restart wipes its JWT cache and recovery means the user logging in again, into its own dedicated decision record. Identifies one asymmetry never previously documented: none of the four broadcast-JWT caches expires an entry when the underlying JWT's own `expiresIn` elapses; only a restart clears it. Keeps the broadcast-cache model as-is. Explicitly rejects local JWKS verification and a persisted/shared cache, with objective criteria for when a shared cache like Redis would earn its place. Decides to add an `expiresIn`-based TTL to close the asymmetry. A 2026-07-15 Update implements the TTL, and the cache-miss-by-restart test, in all four services: `orders-service`, `products-service`, `billing-service` (a new `JwtUserInfo` constructor overload, evicted lazily on the next read that finds an expired entry) and `notification-service` (an optional `expires_at` on `JwtCache.add`). Landed together with `jwt_cache_lookup_total` (see ADR-0036's second Update).
0040	Minimal Kubernetes (kind) deployment as a parallel execution platform, alongside Docker Compose	Accepted	Docker Compose already abstracts several properties of a declarative deployment platform: continuous reconciliation, health checks driving availability/recovery, configuration/application separation, declarative resource representation. A minimal `kind` cluster (`k8s/`) makes them explicit without changing the application. Every service already resolves the others by hostname and already exposes a real `/health` endpoint, so the same images run unchanged, only reused via Kubernetes Service DNS and readiness/liveness probes. Scope: one Namespace, Kustomize base with no overlays, a single PersistentVolumeClaim (Postgres only), Deployment rather than StatefulSet for Postgres/RabbitMQ, since their real value needs more than one replica, which this project doesn't have. `kind` was chosen over Minikube/k3d for running upstream Kubernetes components without a distribution's own substitutions or default-enabled add-ons. Explicit Non-Goals: HA, autoscaling, GitOps, service mesh, cloud provisioning, CI against kind. Docker Compose remains the recommended environment for local development. A 2026-07-17 Update adds the frontend, reusing the same image already built for Docker Compose unmodified.
0041	Kafka vs. RabbitMQ broker benchmark	Accepted	ADR-0007 removed Kafka and kept RabbitMQ as the sole broker, reasoned entirely from workload properties, never measured. A standalone benchmark harness (`benchmarks/broker-comparison/`, its own `docker-compose.yml` and Go module, never part of any service's runtime) ran both brokers side by side on the same machine: publish-then-wait-for-ack throughput (the same call pattern `OutboxPublisher` uses everywhere it exists) and behavior across a hard broker-container restart. RabbitMQ measured roughly 14x the throughput and recovered automatically from the restart; Kafka's default client did not resume publishing within the same test window. A second-broker adapter living inside a real service was considered and rejected — no concrete use case (e.g. offset-based replay) exists today to justify one, so the comparison stays outside the production topology entirely. One new, previously undocumented finding: RabbitMQ's automatic recovery lost 2 of 207 broker-acknowledged messages under the hard kill, a narrow gap in the outbox's at-least-once guarantee (ADR-0037) left open for a future ADR if it recurs.
0042	Fast local dev loop via `docker compose watch`	Accepted	Closes a Low Roadmap item: every code change required a full multi-stage `docker compose build` (no incremental Maven/Go/npm compilation), slow enough on Docker Desktop for Windows to be a real cost during a debugging session. Adopts `docker compose watch`, native to the already-installed Compose version, over Tilt/Skaffold — no new tool to learn or install. Applied via a separate `docker-compose.watch.yml` override, so the default `docker compose up` production path is unchanged. Each service gained a `dev` Dockerfile stage keeping its full toolchain and already-downloaded dependencies in the image: Go services swap the prebuilt binary for `go run`, the four Spring Boot services run `mvn -o spring-boot:run` (offline, reusing the builder stage's cache), reusing `sync+restart`'s container-persistence to get Maven's own incremental compilation across restarts. `notification-service` needed no Dockerfile change at all (`uvicorn --reload` already does in-process hot-reload); the frontend's `dev` stage just skips the production build for `vite dev`'s own HMR. Dependency-manifest and shared-library changes (`pom.xml`, `go.mod`, `package.json`, `correlation-commons`/`correlation-commons-go`) still trigger a full rebuild, automatically.

Roadmap

Click to expand — closed items marked [x], open items [ ]

License

This repository is licensed under the Apache License 2.0. You are free to use, modify, and distribute this code, including for commercial purposes, subject to the terms of that license. See the NOTICE file for a summary of the practices this project demonstrates, and for the attribution requirements that carry over into derivative works.

Easydora is primarily an educational and portfolio project. It exists to demonstrate distributed-systems architecture and engineering practices. It is not meant to be adopted as a dependency or a production platform. Contributions (bug reports, fixes, documentation improvements) are welcome; see CONTRIBUTING.md. The author retains copyright over the original work, as stated in LICENSE and NOTICE.

Disclaimer

This repository was built for learning and portfolio purposes. It demonstrates event-driven microservices architecture, testing discipline, and the kind of decision-making documented throughout the ADR set. It is not intended to be a production-ready commercial platform.

Some external integrations are intentionally simplified. notification-service sends no real email/SMS (see ADR-0014). billing-service's payment provider is not a real payment gateway. Credentials and secrets in this repository's local .env.example are meant for local development only, never for production use.

Architectural decisions throughout this project prioritize demonstrating sound engineering practices, resilience, observability, testing, contract validation, over full business completeness. Known gaps are tracked openly in the Roadmap and in each ADR's own Consequences section, rather than hidden.

Navigation Menu

Repository files navigation

EasyDora

Overview

What This Project Demonstrates

Quick Start

Running on Kubernetes (kind)

Fast local dev loop (`docker compose watch`)

Architecture

Documentation

Service Status

Design notes

Architecture Decision Records

Roadmap

License

Disclaimer

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
api-gateway		api-gateway
auth-service		auth-service
benchmarks/broker-comparison		benchmarks/broker-comparison
billing-service		billing-service
correlation-commons-go		correlation-commons-go
correlation-commons		correlation-commons
docs		docs
e2e-tests		e2e-tests
frontend		frontend
init-scripts		init-scripts
inventory-service		inventory-service
k8s		k8s
notification-service		notification-service
observability		observability
orders-service		orders-service
postman		postman
products-service		products-service
schemas/json		schemas/json
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
SETUP.md		SETUP.md
docker-compose.watch.yml		docker-compose.watch.yml
docker-compose.yml		docker-compose.yml
go.work		go.work
go.work.sum		go.work.sum
pom.xml		pom.xml

Latest commit

History

Folders and files

Repository files navigation

EasyDora

Overview

What This Project Demonstrates

Quick Start

Running on Kubernetes (kind)

Fast local dev loop (docker compose watch)

Architecture

Documentation

Service Status

Design notes

Architecture Decision Records

Roadmap

License

Disclaimer

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Fast local dev loop (`docker compose watch`)