Documentation Index
Fetch the complete documentation index at: https://mintlify.com/microservices-patterns/ftgo-application/llms.txt
Use this file to discover all available pages before exploring further.
The Delivery Service in the FTGO application manages the physical delivery of orders from restaurants to customers. It tracks Delivery and Courier aggregates, schedules couriers when a kitchen ticket is accepted, and cancels delivery assignments when an order is cancelled. The service is entirely event-driven — it reacts to events from the Order Service, Kitchen Service, and Restaurant Service rather than receiving direct commands via saga. This page covers the service’s responsibilities, domain model, REST API, messaging, and database schema.
Responsibilities
- Create
Delivery records when orders are placed, capturing pickup and drop-off addresses
- Schedule a courier for a delivery when the kitchen accepts a ticket (i.e.,
TicketAcceptedEvent is received)
- Cancel delivery assignments when a ticket is cancelled
- Maintain a local replica of restaurant addresses by consuming
RestaurantCreated events
- Allow couriers to update their availability status via the REST API
- Expose a delivery status endpoint showing the assigned courier and planned actions
Domain Model
Delivery
The Delivery aggregate is persisted to the delivery table (JPA @Entity).
| Field | Type | Notes |
|---|
id | Long | Matches the orderId |
state | DeliveryState | PENDING, SCHEDULED, or CANCELLED |
restaurantId | Long | Restaurant for pickup |
pickupAddress | Address (Embedded) | Mapped with column overrides (pickup_street1, etc.) |
deliveryAddress | Address (Embedded) | Mapped with column overrides (delivery_street1, etc.) |
readyBy | LocalDateTime | Set when delivery is scheduled |
pickUpTime | LocalDateTime | Actual pickup time |
deliveryTime | LocalDateTime | Actual delivery time |
assignedCourier | Long | ID of the assigned courier; null when unscheduled or cancelled |
Courier
The Courier aggregate is persisted as a JPA @Entity.
| Field | Type | Notes |
|---|
id | Long | Courier identifier |
available | Boolean | Current availability flag |
plan | Plan (Embedded) | Ordered list of Action items (pickups and dropoffs) |
Plan holds a list of Action objects. When a delivery is scheduled, two actions are added to the courier’s plan: a PICKUP action at readyBy and a DROPOFF action at readyBy + 30 minutes. When a delivery is cancelled, the corresponding actions are removed from the plan.
The current courier assignment algorithm in DeliveryService.scheduleDelivery() is intentionally simplistic — it selects a random available courier from the list. A production implementation would use route optimization.
REST API
The service listens on port 8089.
| Method | Path | Description |
|---|
POST | /couriers/{courierId}/availability | Update a courier’s availability status (available: true/false) |
GET | /deliveries/{deliveryId} | Get delivery status including assigned courier and planned actions. Returns 404 if not found. |
Update courier availability request body
Get delivery status response body
{
"deliveryInfo": {
"deliveryId": 1,
"state": "SCHEDULED"
},
"assignedCourier": 42,
"courierActions": [
{ "type": "PICKUP" },
{ "type": "DROPOFF" }
]
}
Messaging
The Delivery Service is entirely event-driven. It subscribes to events from three channels and triggers domain operations in response.
Events consumed
| Source channel | Event | Handler |
|---|
RestaurantServiceChannels.RESTAURANT_EVENT_CHANNEL | RestaurantCreated | Creates a local Restaurant record with the pickup address |
OrderServiceChannels.ORDER_EVENT_CHANNEL | OrderCreatedEvent | Creates a Delivery record with pickup (restaurant) and drop-off addresses |
KitchenServiceChannels.TICKET_EVENT_CHANNEL | TicketAcceptedEvent | Schedules a courier for the delivery using the readyBy time from the event |
KitchenServiceChannels.TICKET_EVENT_CHANNEL | TicketCancelled | Cancels the delivery and removes courier actions |
The Delivery Service does not participate in any saga as an orchestrator or command-handling participant. All coordination happens through domain events, making it a pure consumer in the FTGO event topology.
Events published
The Delivery Service does not currently publish domain events. Future iterations may emit DeliveryPickedUp and DeliveryDelivered events (stubs are referenced in the Order History Service’s event handler).
Database
The Delivery Service uses MySQL. Key tables:
| Table | Description |
|---|
delivery | The Delivery aggregate: state, addresses, assigned courier, timestamps |
courier | The Courier aggregate: ID and availability flag |
action | The Plan’s Action entries (collection table): type, delivery ID, address, time |
restaurant | Local replica of restaurant data with pickup address |
@AttributeOverride annotations to disambiguate column names for pickup vs. delivery addresses within the delivery table.