Skip to content

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

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

App diagram

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 fresh Drone.
  • 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.

Sequence diagram


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