# googlecloudplatform/transactional-microservice-examples architecture

> Architecture diagram of the GitHub repository googlecloudplatform/transactional-microservice-examples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/transactional-microservice-examples
- Repository: https://github.com/googlecloudplatform/transactional-microservice-examples

## Overview

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: [`services/order-async/main.py`](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-async/main.py) (Order service), [`services/order-processor/order_workflow.yaml.template`](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-processor/order_workflow.yaml.template) (Workflow), [`services/customer-async/main.py`](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/customer-async/main.py) (Customer service), [`services/event-publisher/main.py`](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/event-publisher/main.py) (Event publisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Frontend app<br/>Vite React client"]
end

subgraph group_async["Async saga"]
  node_order_async["Order service<br/>Cloud Run service<br/>[main.py]"]
  node_customer_async["Customer service<br/>Cloud Run service<br/>[main.py]"]
  node_event_publisher["Event publisher<br/>outbox relay<br/>[main.py]"]
end

subgraph group_sync["Sync orchestration"]
  node_order_sync["Order service<br/>REST service<br/>[main.py]"]
  node_customer_sync["Customer service<br/>REST service<br/>[main.py]"]
  node_order_processor["Order processor<br/>workflow client<br/>[main.py]"]
end

subgraph group_cqrs["CQRS example"]
  node_cqrs_order["Order<br/>CQRS service<br/>[main.py]"]
  node_cqrs_orderinfo["Order info<br/>CQRS projection<br/>[main.py]"]
  node_cqrs_product["Product<br/>CQRS service<br/>[main.py]"]
  node_cqrs_event_publisher["Event publisher<br/>CQRS relay"]
  node_cqrs_schema["Schema<br/>[table_schema.json]"]
end

subgraph group_infra["Shared infra"]
  node_order_workflow{{"Workflow"}}
  node_datastore[("Datastore")]
  node_pubsub(("Pub/Sub<br/>messaging bus"))
  node_scheduler(("Scheduler"))
  node_invoker_sa(("Invoker SA<br/>service account"))
end

node_frontend_app -->|"submit order"| node_order_async
node_frontend_app -->|"checkout"| node_order_processor
node_order_async -->|"write order"| node_datastore
node_customer_async -->|"write credit"| node_datastore
node_datastore -->|"scan events"| node_event_publisher
node_scheduler -->|"trigger"| node_event_publisher
node_event_publisher -->|"publish"| node_pubsub
node_pubsub -->|"deliver"| node_order_async
node_pubsub -->|"deliver"| node_customer_async
node_order_async -.->|"order event"| node_customer_async
node_customer_async -.->|"result event"| node_order_async
node_order_processor -->|"start workflow"| node_order_workflow
node_order_workflow -->|"call order"| node_order_sync
node_order_workflow -->|"call customer"| node_customer_sync
node_order_sync -->|"write order"| node_datastore
node_customer_sync -->|"write credit"| node_datastore
node_order_workflow -.->|"use identity"| node_invoker_sa
node_scheduler -.->|"use identity"| node_invoker_sa
node_pubsub -.->|"use identity"| node_invoker_sa
node_cqrs_order -->|"store state"| node_cqrs_schema
node_cqrs_product -->|"store state"| node_cqrs_schema
node_cqrs_orderinfo -->|"read model"| node_cqrs_schema
node_cqrs_event_publisher -.->|"publish events"| node_cqrs_orderinfo

click node_frontend_app "https://github.com/googlecloudplatform/transactional-microservice-examples/tree/main/frontend"
click node_order_async "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-async/main.py"
click node_customer_async "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/customer-async/main.py"
click node_event_publisher "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/event-publisher/main.py"
click node_order_sync "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-sync/main.py"
click node_customer_sync "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/customer-sync/main.py"
click node_order_processor "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-processor/main.py"
click node_order_workflow "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-processor/order_workflow.yaml.template"
click node_cqrs_order "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/cqrs/services/order/main.py"
click node_cqrs_orderinfo "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/cqrs/services/orderinfo/main.py"
click node_cqrs_product "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/cqrs/services/product/main.py"
click node_cqrs_event_publisher "https://github.com/googlecloudplatform/transactional-microservice-examples/tree/main/cqrs/services/event-publisher"
click node_cqrs_schema "https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/cqrs/services/orderinfo/table_schema.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app toneBlue
class node_order_async,node_customer_async,node_event_publisher toneAmber
class node_order_sync,node_customer_sync,node_order_processor toneMint
class node_cqrs_order,node_cqrs_orderinfo,node_cqrs_product,node_cqrs_event_publisher,node_cqrs_schema toneRose
class node_order_workflow,node_datastore,node_pubsub,node_scheduler,node_invoker_sa toneIndigo
```

## Components

### Frontend

Browser client and UI state

- [Frontend app](https://github.com/googlecloudplatform/transactional-microservice-examples/tree/main/frontend): Vite React client · User-facing app that submits orders and views customer/order state · `frontend`

### Async saga

Choreography-based order/customer workflow

- [Order service](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-async/main.py): Cloud Run service · Creates pending orders and records order events · `services/order-async/main.py`
- [Customer service](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/customer-async/main.py): Cloud Run service · Consumes order events, updates credit, and emits result events · `services/customer-async/main.py`
- [Event publisher](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/event-publisher/main.py): outbox relay · Scans stored events and publishes them to Pub/Sub · `services/event-publisher/main.py`

### Sync orchestration

Workflow-driven order/customer workflow

- [Order service](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-sync/main.py): REST service · Synchronous order state mutations for the workflow path · `services/order-sync/main.py`
- [Customer service](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/customer-sync/main.py): REST service · Synchronous credit checks and updates for the workflow path · `services/customer-sync/main.py`
- [Order processor](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-processor/main.py): workflow client · Client-facing entry point that starts the synchronous workflow · `services/order-processor/main.py`

### CQRS example

Alternative pattern example in the repo

- [Order](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/cqrs/services/order/main.py): CQRS service · CQRS write-side example service · `cqrs/services/order/main.py`
- [Order info](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/cqrs/services/orderinfo/main.py): CQRS projection · CQRS read-side or projection service backed by Datastore schema · `cqrs/services/orderinfo/main.py`
- [Product](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/cqrs/services/product/main.py): CQRS service · CQRS example service for product state · `cqrs/services/product/main.py`
- [Event publisher](https://github.com/googlecloudplatform/transactional-microservice-examples/tree/main/cqrs/services/event-publisher): CQRS relay · CQRS example event publication boundary · `cqrs/services/event-publisher`
- [Schema](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/cqrs/services/orderinfo/table_schema.json): Datastore 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](https://github.com/googlecloudplatform/transactional-microservice-examples/blob/main/services/order-processor/order_workflow.yaml.template): Cloud Workflows · Orchestrates the synchronous call sequence across services · `services/order-processor/order_workflow.yaml.template`
- **Datastore**: Cloud Datastore · Per-service state store and outbox-style event store
- **Pub/Sub**: messaging bus · Async fan-out and fan-in transport between services
- **Scheduler**: Cloud Scheduler · Triggers the event publisher on a fixed cadence
- **Invoker SA**: service account · Dedicated runtime identity for Scheduler, Pub/Sub push, and Workflows calls

## Connections

- 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
