ShopFlow — Event-Driven Order Processing

⚡

ShopFlow

Event-Driven Order Processing System

Node.js AWS SNS AWS SQS DynamoDB Express Microservices EDA LocalStack

ShopFlow is a fully working backend system that processes customer orders through an event-driven microservices architecture. A single order placement triggers an autonomous chain of events across five independent services — inventory reservation, payment processing, customer notification, and audit logging — without any service talking directly to another. Built to demonstrate the same architectural patterns used at Amazon, Uber, and DoorDash at scale, deployable on AWS using SNS, SQS, and DynamoDB.

The Business Problem

When a customer places an order on an e-commerce platform, several things must happen: stock must be reserved, payment must be charged, the customer must be notified, and every action must be logged for compliance. In a traditional monolithic or direct-HTTP system, these steps happen sequentially in one service.

The problems with the traditional approach:

If the payment provider is slow, the entire order request hangs and the customer waits
If the notification service crashes, the order may fail even though payment succeeded
Adding a new service (e.g. fraud detection) means modifying existing services
Scaling inventory checks independently is not possible when everything is coupled
A single failure anywhere in the chain can cause data inconsistency

ShopFlow solves all of this by making each responsibility an independent service that reacts to events asynchronously. The Order Service returns in milliseconds — everything else happens in the background.

System Architecture (Interactive Simulation)

Event-Driven Flow: Happy Path

👤

Customer

POST /orders

▶

🛒

Order Service

Express :3000

▶

↙↓↓↘

📬

SQS Queue

[inventory]

📬

SQS Queue

[payment]

📬

SQS Queue

[notification]

📬

SQS Queue

[audit]

▼

📦

Inventory Svc

Reserves stock

💳

Payment Svc

Charges card

🔔

Notification Svc

Sends email

📋

Audit Svc

Logs events

▼

SystemReady. Click "Simulate Order Placed" to visualize the event flow.

Order Status Lifecycle

PENDING → INVENTORY_RESERVED → PAYMENT_PROCESSED → COMPLETED

PENDING → INVENTORY_FAILED (no payment attempted)

PENDING → INVENTORY_RESERVED → PAYMENT_FAILED (stock released)

Services — Deep Dive

🛒

Order Service

Express HTTP Server · Port 3000

Express REST API SNS Producer DynamoDB

The entry point of the system. This is the only service that exposes an HTTP API to the outside world. It accepts order requests, validates them, calculates totals by looking up product prices from DynamoDB, saves the order record, and publishes a single event to SNS. It is the only event producer that starts the chain — every other service reacts to events.

API Endpoints

Method	Path	Description
`POST`	`/orders`	Place a new order. Validates input, looks up prices, saves to DynamoDB, publishes event.
`GET`	`/orders/:orderId`	Fetch current order status and full order record.
`GET`	`/health`	Health check endpoint for load balancer probes.

Request → Response Flow

1Validate request — customerId and items[] must be present and valid
2Look up each productId in DynamoDB inventory table — return 404 if not found
3Calculate totalAmount = sum of (price × quantity) per item
4Save order to DynamoDB with status: PENDING
5Publish order.created event to SNS with full order payload
6Return 201 Created with orderId and status immediately — no waiting for downstream

Events Published

📤 order.created

      Why it returns immediately: The Order Service does not wait for inventory or payment. It publishes one event and responds to the customer in milliseconds. All downstream processing happens asynchronously. This is the core value of EDA — the API is always fast regardless of how slow downstream services are.
    

Sample Request

{
  "customerId": "CUST-001",
  "items": [
    { "productId": "PROD-001", "quantity": 2 }
  ]
}

Sample Response

{
  "message": "Order placed successfully",
  "orderId": "ORD-A1B2C3D4",
  "status": "PENDING",
  "totalAmount": 99.98,
  "items": [
    {
      "productId": "PROD-001",
      "productName": "Wireless Headphones",
      "quantity": 2,
      "unitPrice": 49.99,
      "lineTotal": 99.98
    }
  ]
}

📦

Inventory Service

SQS Consumer · Long-polling

SQS Consumer SNS Producer DynamoDB Atomic Writes

Listens to the inventory SQS queue for order.created events. Its responsibility is to check if every item in the order is in stock and if so, reserve the stock atomically. It has no HTTP server — it is a pure background worker that runs in an infinite polling loop.

Events Consumed / Published

📥 order.created 📤 inventory.reserved 📤 inventory.failed

Processing Logic (Two-Phase Check → Reserve)

1Check phase: Query DynamoDB for every item. If any product is not found or has insufficient stock → immediately publish inventory.failed and stop. No partial reservations.
2Reserve phase: Atomically decrement stock for each item using DynamoDB ConditionExpression: stock >= :qty. This prevents two simultaneous orders from buying the last unit.
3If a race condition is detected (ConditionalCheckFailedException) → publish inventory.failed with an appropriate reason.
4If all items reserved → update order status to INVENTORY_RESERVED → publish inventory.reserved.
5Delete message from SQS (success). On any unhandled error, do NOT delete → SQS retries 3 times → DLQ.

      Why two phases? We check ALL items before reserving ANY. If we reserved item A and then found item B was out of stock, item A would be locked with no order attached. The two-phase approach ensures it's all-or-nothing — consistent with database transaction semantics, but implemented at the application layer.
    

      Why ConditionExpression? Without it, two simultaneous orders for the last unit could both read stock = 1, both pass the check, and both decrement — leaving stock at -1. DynamoDB's conditional write rejects one of them at the database level, making the operation atomic.
    

💳

Payment Service

SQS Consumer · Long-polling

SQS Consumer SNS Producer Simulated Gateway

Listens to the payment SQS queue for inventory.reserved events. Only begins payment processing after inventory is confirmed — never charges a card for an out-of-stock item. Payment is simulated (80% success / 20% decline) with realistic decline reasons and network latency (300–800ms).

Events Consumed / Published

📥 inventory.reserved 📤 payment.processed 📤 payment.failed

Processing Logic

1Extract orderId, customerId, items, totalAmount from the event payload.
2Simulate payment gateway delay (300–800ms) — mimics real API call latency.
380% success: Generate a transaction ID → update order with transactionId and chargedAmount → set status PAYMENT_PROCESSED → publish payment.processed.
420% decline: Pick a realistic decline reason (insufficient funds, card expired, fraud block, etc.) → set status PAYMENT_FAILED → publish payment.failed.

Simulated Decline Reasons

Insufficient funds
Card expired
Transaction declined by issuing bank
Suspected fraud — transaction blocked

      Why payment happens AFTER inventory? We never charge a customer for something we cannot fulfil. The event sequence enforces this business rule architecturally — Payment Service only ever sees inventory.reserved events, so an out-of-stock order never reaches it.
    

🔔

Notification Service

SQS Consumer · Long-polling

SQS Consumer 3 Event Types Terminal Sink

The customer-facing boundary of the system. Listens for all possible terminal events and sends the appropriate message to the customer. It handles three event types and has a dedicated handler for each — the message content and tone changes based on what happened. On success, it also marks the order as fully COMPLETED.

Events Consumed

📥 payment.processed 📥 payment.failed 📥 inventory.failed

Handler per Event Type

Event	Message Sent	Status Update
`payment.processed`	Order confirmation with transaction ID, items, delivery estimate	→ COMPLETED
`payment.failed`	Payment declined notice with reason, prompt to retry	None (already PAYMENT_FAILED)
`inventory.failed`	Out-of-stock notice, no payment taken message	None (already INVENTORY_FAILED)

      Why Notification handles 3 events but Payment only handles 1? Notification is the customer-facing boundary — it must respond to every possible terminal state regardless of which service caused the failure. Payment only cares about one upstream trigger (inventory.reserved) so it has one handler. Services only handle what they own.
    

📋

Audit Service

SQS Consumer · Long-polling

SQS Consumer Append-only Log Event Sourcing

A silent observer that records every single event that flows through the system. Zero business logic — it simply writes an immutable entry to DynamoDB for every message it receives. No other service knows it exists, which is the correct pattern: producers publish events without knowing who is listening. Serves compliance, debugging, and replay requirements.

Events Consumed

📥 ALL events (order.created, inventory.*, payment.*)

What Gets Stored (per event)

Field	Value
orderId	Hash key — groups all events for one order
eventId	Timestamp-prefixed unique ID — sort key for chronological ordering
eventType	e.g. `order.created`, `payment.processed`
payload	Complete snapshot of the event data at that point in time
recordedAt	When the event was published (from SNS)
storedAt	When the audit service wrote the record

Sample Audit Trail for One Order

orderId: ORD-A1B2C3D4
─────────────────────────────────────────────────────
[2026-05-07T10:00:00Z]  order.created
[2026-05-07T10:00:01Z]  inventory.reserved
[2026-05-07T10:00:02Z]  payment.processed

      Why sequential processing here? Unlike other services that use Promise.all() for speed, the Audit Service processes messages one by one to preserve write order in DynamoDB. For a compliance log, chronological accuracy matters more than throughput.
    

EDA Patterns Demonstrated

📡 Pub / Sub Fan-out

Order Service publishes one event to SNS. SNS delivers a copy to all 4 subscriber queues simultaneously. Adding a 5th service (e.g. fraud detection) requires zero changes to any existing service — just subscribe the new queue to SNS.

📬 Async Decoupling via SQS

Producers and consumers never communicate directly. If Inventory Service goes down, messages wait in the queue and are processed when it recovers. The Order API returns instantly regardless of downstream health.

🔁 Dead Letter Queue (DLQ)

Every SQS queue has a paired DLQ. If a message fails processing 3 times (e.g. a corrupt payload or a service bug), it moves to the DLQ automatically. No message is silently lost. Operations can inspect and replay DLQ messages.

📖 Event Sourcing

The Audit Service builds an immutable, append-only log of every event. You can reconstruct the complete state of any order by replaying its event history. This is the foundation of CQRS and event-sourced systems.

⚛️ Atomic Conditional Writes

Stock reservation uses DynamoDB's ConditionExpression to prevent overselling under concurrent load. Two simultaneous orders for the last unit cannot both succeed — one gets rejected at the database level.

🔗 Correlation ID Threading

The orderId flows through every event in the chain. Any log line from any service can be correlated back to the originating order. This is the foundation of distributed tracing — same principle as X-Ray, Jaeger, and Datadog APM.

📊 At-Least-Once Delivery

SQS guarantees every message will be delivered at least once. Services must be designed to handle duplicate messages gracefully (idempotency). The visibility timeout hides a message while it's being processed.

🧱 Single Responsibility

Each service owns exactly one concern. Order Service knows about orders. Payment Service knows about payments. No service knows how other services work internally — they only communicate through events.

Data Model

🗄️ DynamoDB Tables

Table	Partition Key	Sort Key	Used By
shopflow-orders	orderId	—	Order, Inventory, Payment, Notification Services
shopflow-inventory	productId	—	Order Service (price lookup), Inventory Service (stock)
shopflow-events	orderId	eventId	Audit Service

Sample product data seeded on startup:

productId	Name	Stock	Price
PROD-001	Wireless Headphones	15	$49.99
PROD-002	Mechanical Keyboard	0	$89.99 (intentionally out of stock)
PROD-003	USB-C Hub	30	$29.99

Technology Stack

🟩

Node.js + Express

Runtime and HTTP framework for the Order Service REST API

📡

AWS SNS

Event bus — fan-out pub/sub to all subscriber queues simultaneously

📬

AWS SQS

Per-service message queues with DLQs and 3-retry redrive policy

⚡

AWS DynamoDB

NoSQL store for orders, inventory, and append-only event log

🐳

Docker + LocalStack

Full local AWS simulation — develop and test without cloud costs

☁️

AWS CDK (planned)

Infrastructure as code — deploy entire stack to AWS with one command

How to Run Locally

Prerequisites: Node.js 18+, Docker Desktop running

Clone and install

git clone https://github.com/phpfriend/event-driven-architecture
cd event-driven-architecture
npm install

Start local AWS infrastructure (Terminal 1)

Starts LocalStack, creates SNS topic, 4 SQS queues + DLQs, 3 DynamoDB tables, seeds inventory data.

npm run infra:up

Start all 5 services (Terminal 2)

Launches all services with color-coded output per service — cyan (Order), green (Inventory), yellow (Payment), magenta (Notification), blue (Audit).

npm run dev:all

Run end-to-end tests (Terminal 3)

Places 3 orders (happy path, out-of-stock, multi-item) and polls status until each reaches a terminal state.

npm run test:order

Inspect audit trail for any order

node scripts/check-order.js ORD-XXXXXXXX

Why Event-Driven Architecture?

Problem	EDA Solution
Payment provider is slow	Payment Service runs independently — Order API returns in milliseconds regardless
Notification service crashes	Message stays in SQS queue, delivered when service recovers — no data loss
Need to add Fraud Detection service	Subscribe it to SNS — zero changes to any existing service
Two customers race for last item	DynamoDB conditional write rejects one atomically — no overselling possible
Compliance audit requirement	Audit Service passively records everything — producers don't know it exists
Scale inventory checks independently	Deploy more consumers for the inventory queue — other services unaffected
Debug a failed order in production	Query the event log for the orderId — full history, timestamped, immutable