How googlecloudplatform/transactional-microservice-examples works
1. This repository is a Google Cloud reference app for transactional workflows in a microservices architecture. It contains two backend variants of the same order/customer business process: an asynchronous choreography-based saga and a synchronous orchestration flow.
2. The main runtime for server-side components is Python on Cloud Run. Persistent state lives in Cloud Datastore. Asynchronous messaging uses Pub/Sub, scheduled publishing uses Cloud Scheduler, and synchronous coordination uses Cloud Workflows.
3. The shared business boundary is simple and split by ownership: the Order service owns order state, and the Customer service owns customer credit state. The workflow is: create an order, reserve/update customer credit, then mark the order accepted or rejected depending on whether the credit limit is exceeded.
4. In the choreography-based saga, the main services are services/order-async, services/customer-async, and services/event-publisher. The Order service creates orders as pending, stores an event record in Datastore, and later updates order status when it receives a customer result event. The Customer service consumes order events, updates credit, and emits success/failure events.
5. The event publishing path is deliberately decoupled from business writes. Services persist events into Datastore first, and event-publisher periodically scans for unpublished events and sends them to Pub/Sub. This is the repo’s outbox-style boundary: database write and event recording are atomic; publication is eventually consistent.
6. Pub/Sub is used as the fan-out/fan-in transport between the two async services. Push subscriptions deliver topic messages directly into Cloud Run HTTP endpoints, with IAM-protected invocations. Because Pub/Sub can redeliver messages, the consumers also maintain ProcessedEvent state in Datastore to make event handling idempotent.
7. In the synchronous orchestration variant, the services are services/order-sync, services/customer-sync, and services/order-processor. The order-processor is the client-facing entry point; it starts a workflow that calls the Order and Customer services synchronously over REST, then returns the final accepted/rejected order result.
8. Cloud Workflows is the orchestrator boundary in the synchronous path. It centralizes the call sequence, so the services themselves stay focused on data mutations and query/update APIs rather than cross-service coordination.
9. The infrastructure wiring is part of the architecture: Cloud Scheduler triggers the async event publisher every minute, and a dedicated Cloud Run invoker service account is used for Scheduler, Pub/Sub push delivery, and Workflows HTTP calls. This makes service-to-service access explicit and locked down.
10. The frontend is a separate Vite + React + TypeScript app under frontend/. It is organized around pages and contexts for cart, customer, identity token, and orders, plus API hooks. Architecturally it acts as the user-facing client that calls either the async or sync backend endpoints and manages browser-side state.
11. The cqrs/ subtree is a second example application in the repo. It mirrors the same Cloud Run/Datastore/event-publishing style but with a CQRS-shaped split: order, orderinfo, product, and event-publisher, plus a Datastore schema/index definition. That makes the repository more of a pattern catalog than a single app.
12. For a diagram, the key boundaries are: user/UI, Cloud Run microservices, Datastore as per-service state and event store, Pub/Sub as async event transport, Scheduler as periodic trigger, and Workflows as the synchronous orchestrator. The main data flow is order submission → order persistence → customer credit evaluation → order finalization.
Main entry points: order-async/main.py Order service · order_workflow.yaml.template Workflow · customer-async/main.py Customer service · event-publisher/main.py Event publisher
Components 17
Frontend
Browser client and UI state
- Frontend app · User-facing app that submits orders and views customer/order state
frontend
Async saga
Choreography-based order/customer workflow
- Order service · Creates pending orders and records order events
services/order-async/main.py - Customer service · Consumes order events, updates credit, and emits result events
services/customer-async/main.py - Event publisher · Scans stored events and publishes them to Pub/Sub
services/event-publisher/main.py
Sync orchestration
Workflow-driven order/customer workflow
- Order service · Synchronous order state mutations for the workflow path
services/order-sync/main.py - Customer service · Synchronous credit checks and updates for the workflow path
services/customer-sync/main.py - Order processor · Client-facing entry point that starts the synchronous workflow
services/order-processor/main.py
CQRS example
Alternative pattern example in the repo
- Order · CQRS write-side example service
cqrs/services/order/main.py - Order info · CQRS read-side or projection service backed by Datastore schema
cqrs/services/orderinfo/main.py - Product · CQRS example service for product state
cqrs/services/product/main.py - Event publisher · CQRS example event publication boundary
cqrs/services/event-publisher - Schema · Datastore table and index definition for the CQRS example
cqrs/services/orderinfo/table_schema.json
Shared infra
Messaging, scheduling, orchestration, and state store
- Workflow · Orchestrates the synchronous call sequence across services
services/order-processor/order_workflow.yaml.template - Datastore · Per-service state store and outbox-style event store
- Pub/Sub · Async fan-out and fan-in transport between services
- Scheduler · Triggers the event publisher on a fixed cadence
- Invoker SA · Dedicated runtime identity for Scheduler, Pub/Sub push, and Workflows calls
Connections 23
- Frontend app → Order service: submit order · Frontend can call the asynchronous backend path
- Frontend app → Order processor: checkout · Frontend can call the synchronous backend entry point
- Order service → Datastore: write order · Persists order state and outbox event records
- Customer service → Datastore: write credit · Updates customer credit state and processed-event records
- Datastore → Event publisher: scan events · Publisher reads unpublished events from Datastore
- Scheduler → Event publisher: trigger · Runs the publisher periodically
- Event publisher → Pub/Sub: publish · Sends stored events to Pub/Sub topics
- Pub/Sub → Order service: deliver · Push delivery of customer result or order events into Cloud Run
- Pub/Sub → Customer service: deliver · Push delivery of order events into Cloud Run
- Order service → Customer service: order event · Logical async handoff through Pub/Sub and Datastore outbox
- Customer service → Order service: result event · Logical async result back to order service
- Order processor → Workflow: start workflow · Client entry point starts the orchestration
- Workflow → Order service: call order · Workflow invokes order service synchronously
- Workflow → Customer service: call customer · Workflow invokes customer service synchronously
- Order service → Datastore: write order · Synchronous order state persistence
- Customer service → Datastore: write credit · Synchronous customer credit update persistence
- Workflow → Invoker SA: use identity · Workflow and service calls run under a dedicated invoker identity
- Scheduler → Invoker SA: use identity · Scheduler uses the shared invoker service account
- Pub/Sub → Invoker SA: use identity · Push subscriptions invoke Cloud Run with IAM protection
- Order → Schema: store state · CQRS write side persists into the shared schema
- Product → Schema: store state · CQRS service persists product state
- Order info → Schema: read model · CQRS projection uses the Datastore schema/indexes
- Event publisher → Order info: publish events · CQRS event relay updates the read side indirectly