Design
This document explains how the system is built: its overall architecture, the architectural patterns it applies, and the diagrams that illustrate its structure and behaviour.
Use Case Diagram

Architectural Style
The system follows a microservice architecture. Both the drone and customer domains are designed as independent microservices, with a "middleman" Delivery Service sitting between them to allow richer coordination logic over incoming orders (for example, choosing how and when an order is fulfilled).
Key properties of the style:
- Loose coupling — services share no database and never call each other synchronously.
- Asynchronous, event-driven communication — every interaction flows through RabbitMQ.
- Independent deployability — each service is its own Gradle module and Docker image.
- Single entry point — clients only ever talk to the Caddy API gateway.
High-level Structure

client ──REST──▶ Caddy (gateway) ──REST──▶ Customer Service ─┐
Drone Service ──┤── REST (queries)
│
Customer ⇄ Delivery ⇄ Drone ──── all via RabbitMQ ───────┘
│
MongoDB (SAGA state, drone event store)
Prometheus (metrics scraping)
Applied Patterns
1. API Gateway (Caddy)
All external traffic enters through Caddy, which acts as a reverse proxy and single entry point. It hides the internal topology from clients and provides stable, friendly paths:
/api/orders*→ Customer Service/api/drones*→ Drone Service/prometheus*→ Prometheus/customer/actuator*,/drone/actuator*→ per-service Actuator endpoints
The gateway strips the public prefix before forwarding, so POST /api/orders reaches the Customer
Service as POST /. See the Caddyfile and the API document.
2. SAGA — Orchestration (Customer Service)
Because an order spans three services, the system uses the SAGA pattern to manage the
distributed transaction without a global ACID transaction. The Customer Service hosts the
orchestrator (OrderSagaOrchestrator), which drives the flow and reacts to events.
Happy path (forward flow):
| Step | Name | Owner | Success event |
|---|---|---|---|
| 1 | ORDER_VALIDATION |
Customer Service | OrderValidatedEvent |
| 2 | DELIVERY_SCHEDULING |
Delivery Service | DeliveryScheduledEvent |
| 3 | DRONE_ASSIGNMENT |
Drone Service | DroneAssignedEvent |
COMPLETED |
Customer Service | OrderCompletedEvent |
The SAGA's current state (status, current step, completed steps, failure reason, timestamps) is
persisted in MongoDB as an OrderSagaState document, so progress survives restarts and can be
queried at any time via GET /api/orders/{orderId}/saga-status.
SAGA status lifecycle:
STARTED ──▶ (running steps) ──▶ COMPLETED
│
├──▶ FAILED ──▶ COMPENSATING ──▶ COMPENSATED
Compensation (rollback): if a step fails after earlier steps succeeded, the orchestrator runs compensating transactions in reverse order of completion:
| Failed step | Compensating events published |
|---|---|
| Order validation | none (nothing to undo) → order cancelled |
| Delivery scheduling | CompensateOrderEvent |
| Drone assignment | CompensateDroneEvent, then CompensateDeliveryEvent, CompensateOrderEvent |
Compensation handlers live close to the resource they undo:
SagaEventListener (Customer) handles order compensation (refund / restore inventory), and
DroneCompensationListener (Drone) detaches the drone and returns it to the pool.
All SAGA events extend a common SagaEvent base type (in the common module) and are routed
through a RabbitMQ topic exchange (saga_events_exchange) using saga.* routing keys.
3. Event Sourcing (Drone Service)
The Drone Service does not store the current state of a drone directly. Instead, it records every
state change as an immutable event in MongoDB (the DroneEventStore), and reconstructs the
current state by replaying those events.
Event types (DroneEvent subtypes):
DRONE_CREATED ──▶ DRONE_DISPATCHED ──▶ DRONE_DELIVERED ──▶ DRONE_RETURNED
Each event carries a monotonically increasing version (the per-drone event count) for ordering. Benefits realised here:
- Full audit trail — the complete history of every drone is queryable
(
GET /api/drones/drone/{droneId}/events). - State reconstruction — current state is rebuilt on demand
(
GET /api/drones/drone/{droneId}/rebuild) by folding events over a freshDrone. - Temporal queries — the same history is also queryable per order
(
GET /api/drones/order/{orderId}/events).
A scheduled task (@Scheduled, every 10 s) checks in-flight drones and, once a drone's expected
arrival time passes, records the DRONE_DELIVERED and DRONE_RETURNED events — simulating the
physical delivery lifecycle (FR-04).
4. Health Checks
Every service exposes a lightweight /health endpoint and a Spring Boot Actuator health
endpoint. Docker Compose uses these for container health checks, and dependent services only start
once RabbitMQ reports healthy.
5. Metrics
Each service publishes metrics via Micrometer to a Prometheus registry, exposed at
/actuator/prometheus. Alongside JVM/HTTP technical metrics, the system records business
metrics, e.g.:
business_orders_created_total— orders accepted by the Customer Service.saga_started_total,saga_completed_total,saga_failed_total,saga_compensated_total— SAGA outcomes.drone_sent— gauge of currently dispatched drones.
Prometheus scrapes all three services (see prometheus.yml).
6. Distributed Tracing
Tracing is enabled through Micrometer Observation with sampling probability 1.0 (100%).
Observation is turned on for both the RabbitMQ template and listeners
(spring.rabbitmq.template.observation-enabled / listener.simple.observation-enabled), so a
single trace context is propagated across REST calls and asynchronous AMQP messages. This makes
it possible to follow one order's journey end-to-end across all three services.
Sequence Diagram
The end-to-end flow of a successful order — from REST request, through the SAGA, to drone delivery.

See API for the concrete endpoints and message contracts, and Deployment for how the pieces are wired together at runtime.