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 Order Service is the central coordinator of the FTGO application. It manages the full lifecycle of a customer order — from initial placement through approval, revision, and cancellation — and drives the distributed transactions that coordinate across Consumer, Kitchen, and Accounting services via the Saga pattern. This page covers the service’s responsibilities, domain model, REST API, messaging interactions, and database schema.
Responsibilities
- Accept new order requests from the API Gateway and persist them as
Order aggregates
- Orchestrate the CreateOrderSaga to verify the consumer, create a kitchen ticket, and authorize payment in a single distributed transaction
- Orchestrate the CancelOrderSaga to reverse a kitchen ticket and payment authorization when a customer cancels
- Orchestrate the ReviseOrderSaga to adjust line-item quantities while keeping the kitchen and accounting services consistent
- Publish domain events (
OrderCreated, OrderAuthorized, OrderCancelled, OrderRejected, OrderRevised) so downstream services can react
- Maintain a local replica of restaurant menus by consuming
RestaurantCreated and RestaurantMenuRevised events
Domain Model
The core aggregate is Order, persisted to the orders table.
| Field | Type | Notes |
|---|
id | Long | Auto-generated primary key |
version | Long | Optimistic locking version |
state | OrderState | Enum stored as VARCHAR |
consumerId | Long | Reference to the placing consumer |
restaurantId | Long | Reference to the target restaurant |
orderLineItems | Embedded | Collection of OrderLineItem |
deliveryInformation | Embedded | Delivery time and address |
paymentInformation | Embedded | Payment details |
orderMinimum | Money | Minimum order total enforced on revisions |
Order states
APPROVAL_PENDING → APPROVED → CANCEL_PENDING → CANCELLED
↘ REVISION_PENDING → APPROVED
↘ REJECTED
APPROVAL_PENDING the moment it is saved. The CreateOrderSaga moves it to either APPROVED (via noteApproved()) or REJECTED (via noteRejected()). Cancellation and revision both go through intermediate pending states to support saga compensation.
The Order aggregate enforces the order minimum on revisions — if the revised total meets or exceeds orderMinimum, an OrderMinimumNotMetException is thrown before the saga begins.
REST API
The service listens on port 8082. All endpoints are under the /orders path.
| Method | Path | Description |
|---|
POST | /orders | Create a new order; returns { orderId }. Kicks off CreateOrderSaga. |
GET | /orders/{orderId} | Retrieve order state and total. Returns 404 if not found. |
POST | /orders/{orderId}/cancel | Begin cancellation via CancelOrderSaga. Returns 404 if not found. |
POST | /orders/{orderId}/revise | Adjust line-item quantities via ReviseOrderSaga. Returns 404 if not found. |
Create order request body
{
"consumerId": 1,
"restaurantId": 2,
"deliveryTime": "2026-05-21T18:30:00",
"deliveryAddress": {
"street1": "9 Amazing View",
"city": "Oakland",
"state": "CA",
"zip": "94612"
},
"lineItems": [
{ "menuItemId": "kl", "quantity": 1 }
]
}
Revise order request body
{
"revisedOrderLineItems": [
{ "menuItemId": "kl", "quantity": 2 }
]
}
Messaging
Events published
The OrderDomainEventPublisher emits the following events on the net.chrisrichardson.ftgo.orderservice.domain.Order channel:
| Event | Trigger |
|---|
OrderCreatedEvent | New order saved; contains OrderDetails, delivery address, and restaurant name |
OrderAuthorized | CreateOrderSaga completes successfully |
OrderRejected | CreateOrderSaga fails (consumer or payment validation) |
OrderCancelled | CancelOrderSaga confirms cancellation |
OrderRevisionProposed | ReviseOrderSaga begins; includes old and new totals |
OrderRevised | ReviseOrderSaga confirms revision |
Events consumed
| Source aggregate | Event | Handler |
|---|
RestaurantService.Restaurant | RestaurantCreated | Creates a local menu replica via OrderService.createMenu() |
RestaurantService.Restaurant | RestaurantMenuRevised | Updates the local menu replica via OrderService.reviseMenu() |
Saga command channels
The Order Service orchestrates sagas that send commands to:
consumerService — ValidateOrderByConsumerkitchenService — CreateTicket, ConfirmCreateTicket, CancelCreateTicket, BeginCancelTicketCommand, ConfirmCancelTicketCommand, BeginReviseTicketCommand, ConfirmReviseTicketCommandaccountingService — AuthorizeCommand, ReverseAuthorizationCommand, ReviseAuthorization
The Order Service is the saga orchestrator. It creates saga instances via SagaInstanceFactory and drives the saga state machine, but does not handle saga commands itself — those are handled by the participant services.
Database
The Order Service uses MySQL (shared Eventuate Tram schema). Key tables:
| Table | Description |
|---|
orders | The Order aggregate: state, consumer ID, restaurant ID, delivery info, payment info |
order_line_items | @ElementCollection embedded within the orders table (via OrderLineItems) |
restaurants | Local replica of restaurant data including menu items used for line-item validation |
saga_instances table. Transactional outbox messages are written to the message table and relayed by the CDC service (Eventuate Tram CDC).
Because orders start in APPROVAL_PENDING before the saga completes, clients should poll GET /orders/{orderId} or consume OrderAuthorized/OrderRejected events to determine the final state rather than assuming the POST /orders response reflects approval.