Drone Delivery Platform — Documentation
Abstract
We want to build an online system for delivering packages through drones (delivery drones), offered as a service.
The basic need is simple: a user wants to send a package (of a given weight) from one place to another, on a specific date/time (including immediately) and within a maximum amount of time. The user may also want to track the delivery — knowing where the package is and how much time is left before it arrives.
This documentation describes the architecture, domain model, public API and operational setup of the system that fulfils that need.
Overview
The platform is a microservice-based system. Business capabilities are split into three independently deployable services, supported by a shared library and a set of infrastructure components.
| Component | Type | Responsibility |
|---|---|---|
| Customer Service | Microservice | Accepts orders over REST and orchestrates the whole delivery SAGA. |
| Delivery Service | Microservice | Coordinates fulfilment between an order and the drone fleet. |
| Drone Service | Microservice | Manages the drone fleet and simulates the physical delivery. |
| common | Shared library | Cross-service message and event contracts (DTOs). |
| Caddy | API Gateway | Single entry point; reverse-proxies REST traffic to the services. |
| RabbitMQ | Message broker | Asynchronous, event-driven communication between services. |
| MongoDB | Database | Persists SAGA state and the drone event store. |
| Prometheus | Monitoring | Scrapes and stores service metrics. |
Services never call each other synchronously. All inter-service communication happens asynchronously through RabbitMQ, which keeps the services loosely coupled and resilient.
Architecture at a glance
┌─────────────────────────────────────────────┐
HTTP (REST) │ Caddy │
client ─────────▶ │ (API Gateway :8080) │
└───────┬───────────────────────┬─────────────┘
│ /api/orders* │ /api/drones*
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Customer Service │ │ Drone Service │
│ (SAGA orches- │ │ (Event Sourcing) │
│ trator) │ │ │
└───────┬──────────┘ └────────┬─────────┘
│ ▲ ▲ │
publish / │ │ saga events │ │ saga events
consume ▼ │ │ ▼
┌─────────────────────────────────────────────┐
│ RabbitMQ │
│ order_queue · drone_queue · saga exchange │
└───────────────────────┬─────────────────────┘
▲ │
publish / │ ▼ consume
┌──────────────────┐
│ Delivery Service │
└──────────────────┘
MongoDB ◀── SAGA state (customer) + drone event store (drone)
Prometheus ◀── /actuator/prometheus on every service
A typical order travels through the system as a distributed transaction coordinated by the SAGA pattern (see Design):
- The client
POSTs an order to the gateway, which forwards it to the Customer Service. - The Customer Service starts a SAGA, validates the order, and publishes events on RabbitMQ.
- The Delivery Service consumes the order and asks the drone fleet to take it.
- The Drone Service assigns a drone, records the assignment as an event, and simulates flight.
- Each step reports back via SAGA events; if any step fails, compensating transactions roll the others back.
Applied architectural patterns
This project demonstrates a set of well-known distributed-system patterns. Each is described in detail in Design.
| Pattern | Where | Purpose |
|---|---|---|
| API Gateway | Caddy | Single, stable entry point and routing for all clients. |
| SAGA (orchestration) | Customer Service | Manages a multi-service transaction with compensation. |
| Event Sourcing | Drone Service | Stores every drone state change as an immutable event. |
| Health Check | All services (/health, actuator) |
Lets the orchestrator/gateway know a service is alive. |
| Metrics | Micrometer + Prometheus | Exposes business and technical metrics for monitoring. |
| Distributed Tracing | Micrometer Observation (REST + AMQP) | Propagates a trace context across service boundaries. |
Technology stack
- Language / Runtime: Java 21
- Framework: Spring Boot 3.3.x (Web, AMQP, Data MongoDB, Actuator)
- Build: Gradle (multi-module, Kotlin DSL)
- Messaging: RabbitMQ 3.13
- Database: MongoDB
- Gateway: Caddy 2
- Monitoring: Prometheus + Micrometer
- Packaging: Docker / Docker Compose
Build & run
# Build all modules
./gradlew build
# Start the whole stack (services + infrastructure)
docker-compose up --build
Once the stack is up:
- Gateway / API: http://localhost:8080
- Caddy admin API: http://localhost:8081
- RabbitMQ management UI: http://localhost:15672 (guest / guest)
- Prometheus: http://localhost:8080/prometheus
A ready-made end-to-end smoke test is available in teste2e.sh, which boots the stack, submits an
order and verifies the SAGA reaches COMPLETED.
See the Deployment Guide for full details.
Documentation map
| Document | Contents |
|---|---|
| Domain | Domain model, ubiquitous language and bounded contexts. |
| Analysis | Functional and non-functional requirements. |
| Design | Architecture, applied patterns, sequence and context diagrams. |
| API | REST endpoints, message queues and shared data structures. |
| Deployment | Prerequisites, build, run, configuration and troubleshooting. |