How to Build Template 2: E-Commerce Platform

How to Build Template 2: E-Commerce Platform

This template shows how to model an e-commerce platform at the Container level. It is designed to make the internal structure explicit: apps, gateway, services, databases, event flow, and external providers.

The Container diagram is the right zoom level here because e-commerce systems are not monolithic. They are composed of multiple independently deployable units — each owning its data, each with a distinct responsibility. Understanding those units and how they communicate is the foundation of any serious technical conversation about the platform.

What This Template Shows

• Web, mobile, and admin applications as separate deployable frontends
• A single API Gateway acting as the only entry point from external clients
• Core backend services — orders, catalog, customers, payments, and notifications — each isolated behind its own boundary
• Owned databases per service, making data responsibility explicit
• A message broker connecting services asynchronously for post-order side effects
• External providers for payments, search indexing, email, and SMS

This is the right level when you want to explain how the system is decomposed internally, not just what it connects to. It answers questions like: who owns the product data, what happens after an order is placed, and which services can fail without taking the checkout flow down with them.

Embedded Diagram

Why This Container Diagram Works

The main architectural signal this template communicates is the separation between:

• the synchronous order path — what must succeed for a purchase to complete
• the asynchronous post-order path — what happens after the order is confirmed

That distinction is not just organizational. It is a resilience guarantee. An order can be persisted and confirmed to the customer even if the notification service is temporarily down, the loyalty system is lagging, or a downstream ERP integration is degraded. The message broker absorbs the backpressure and delivers events when the downstream system recovers.

The second important signal is the database-per-service pattern. Each service owns its own store. The order service cannot query the product catalog database directly — it has to go through the catalog service API. That constraint forces explicit contracts between teams and prevents the tight coupling that makes large systems fragile over time.

The API Gateway is a third key signal. It is the only container that faces the public internet. Every client — web, mobile, admin — communicates through it. This gives the architecture a clear enforcement point for authentication, rate limiting, and routing. Internal services communicate with each other directly or via the broker, not through the gateway.

Core Containers To Include

User-Facing Applications

Web Application The primary browser-based shopping interface. It handles product discovery, cart management, checkout flow, order history, and account management. In modern implementations this is often a React or Next.js application served from a CDN, with server-side rendering for SEO-critical product pages. It communicates exclusively through the API Gateway — never to backend services directly.

iOS Mobile Application The native iOS shopping experience. Mobile apps typically need a leaner API surface than the web app because network conditions are less reliable. They also add mobile-specific concerns such as push notification subscriptions and native payment integrations like Apple Pay. This container represents the iOS client specifically because iOS and Android often have different release cycles and different feature parity agreements.

Android Mobile Application Same role as the iOS app but on Android. Keeping these as separate containers in the diagram reflects reality: they are different codebases (or at minimum different deployment targets), may ship at different times, and may support different feature sets during rollout periods.

Admin Application The internal back-office tool used by merchandising, operations, and customer service teams. This is a separate application because it has fundamentally different security requirements — it should not be on the same domain or auth flow as the public storefront — and different performance characteristics. Admin tools often need more complex data views, bulk operations, and reporting functionality that would be inappropriate to build into the public API surface.

Boundary and Core Services

API Gateway The single entry point for all external traffic. The gateway is responsible for authentication token validation, request routing to the correct backend service, rate limiting, SSL termination, and request/response transformation where needed. In AWS this might be an API Gateway + Lambda authorizer combination, or an nginx-based solution like Kong. Critically, the gateway does not contain business logic — it routes and protects.

Order Service The transactional core of the platform. It handles cart-to-order conversion, order state management (placed, confirmed, processing, shipped, delivered, returned, refunded), and is the source of truth for purchase history. Order creation is a multi-step flow: it calls the Product Catalog Service to validate availability, calls the Payment Service to capture funds, writes the order to its own database, and then publishes an OrderPlaced event to the message broker. If any synchronous step fails, the order is not created. If the broker or downstream consumers fail, the order is still persisted — the event will be retried.

Product Catalog Service Owns everything about what is being sold: product listings, descriptions, images, pricing, categories, variants (size, color), and inventory levels. This service answers the questions "what can a customer buy" and "is it available." It also publishes events when products are updated, which allows the Search Service to re-index without the catalog service having to know about search directly.

Customer Service Manages customer accounts: registration, authentication tokens (or delegates to an identity provider), address book, saved payment methods, preferences, and communication opt-ins. It is intentionally separated from the Order Service because customer identity is stable across many orders, and because customer data privacy concerns (GDPR deletion requests, data export requests) should be isolated to one service rather than spread across multiple.

Payment Service The boundary between the platform and external payment processors. It holds no payment card data — that responsibility is outsourced to Stripe or Braintree via tokenization. The payment service manages payment intents, captures, refunds, and dispute handling. It writes payment records to its own database for audit purposes and reconciliation. Keeping this as a separate service allows PCI-DSS scope to be narrowed: only this service and its infrastructure need full PCI compliance audit coverage.

Notification Service Responsible for all outbound customer communications: order confirmation emails, shipping updates, delivery alerts, and promotional messages. It is entirely event-driven — it subscribes to events from the message broker (OrderPlaced, OrderShipped, OrderDelivered) and triggers the appropriate messages. It integrates with SendGrid or a similar email API for email, and with Twilio for SMS. The notification service has no API surface toward other internal services — it only consumes events.

Shared Infrastructure

Message Broker The event backbone for asynchronous flows. The broker — typically Apache Kafka, RabbitMQ, or AWS SQS/SNS depending on scale — decouples event producers from consumers. When the Order Service publishes OrderPlaced, it does not know or care what happens next. The Notification Service, the Warehouse Fulfillment System, the Loyalty Service, and the Analytics Pipeline can all subscribe independently. New consumers can be added without changing the Order Service. This is the foundation of extensibility.

Search Service Provides fast, relevance-ranked product search across the catalog. The product database is optimized for transactional access patterns; full-text search requires a different engine. Elasticsearch or Algolia is typical here. The search index is built asynchronously from catalog events — when a product is updated, the catalog service publishes an event, and the search service consumes it and updates the index. Search queries come through the API Gateway directly to this service, not through the Catalog Service.

Data Stores

Orders Database Typically a relational database (PostgreSQL) because orders have strong consistency requirements, transactional guarantees, and complex relational queries (order lines, discounts, shipping addresses, returns). The order service owns this database exclusively.

Product Database Often a combination of a relational store for structured product attributes and an object store (S3) for product images. The product catalog service owns this database exclusively. Other services that need product information must call the catalog service API.

Customer Database A relational database holding account credentials, profiles, addresses, and preferences. The customer service owns this exclusively. GDPR compliance — right to deletion, data portability — is enforced at the service boundary.

Payment Database A highly auditable append-only store for payment records. Every payment event — intent created, authorized, captured, refunded — is written as an immutable record. This enables reconciliation against the payment processor's reports and provides a clear audit trail for disputes and chargebacks.

How The Order Flow Works

Understanding the step-by-step flow through the diagram makes the architecture concrete:

1. The customer adds items to the cart and clicks checkout. The Web Application calls the API Gateway.
2. The API Gateway validates the auth token with the Customer Service, then routes the checkout request to the Order Service.
3. The Order Service calls the Product Catalog Service to confirm product availability and lock inventory.
4. The Order Service calls the Payment Service to initiate a payment capture.
5. The Payment Service calls Stripe to process the charge. On success, it writes a payment record and returns a confirmation.
6. The Order Service writes the confirmed order to the Orders Database and publishes an OrderPlaced event to the Message Broker.
7. The API Gateway returns a 200 to the Web Application. The customer sees the confirmation screen.
8. Asynchronously, the Notification Service picks up the OrderPlaced event and sends a confirmation email via SendGrid and a confirmation SMS via Twilio.
9. The Warehouse Fulfillment System (external) also picks up the event and begins the pick-and-pack process.

Steps 1 through 7 are synchronous and must complete for the order to succeed. Steps 8 and 9 are asynchronous and their temporary failure does not affect the order outcome.

How To Adapt It

If your organization uses fewer services, you can collapse some of them without losing the core architectural signal:

• Combine catalog and search if your catalog is small enough that a database full-text index is sufficient — but be aware this creates coupling that may need to be undone at scale.
• Merge customer and order domains if the product is early-stage and team size does not yet justify the split. Mark the merge explicitly in the diagram so the debt is visible.
• Replace the broker with direct async jobs (background workers, cron tasks) if Kafka or RabbitMQ would be operational overhead you are not ready for. Direct jobs are simpler but harder to fan out to multiple consumers.

If your architecture is more advanced, you can expand the template:

• Add an Inventory Service separate from the catalog if inventory management has its own complexity — warehouse locations, reservations, replenishment cycles.
• Add a Warehouse Fulfillment Service to represent the pick-pack-ship workflow after order placement.
• Add a Fraud and Risk Service that intercepts the order placement flow before payment capture, scoring the order for risk signals and either approving, flagging, or declining.
• Add a Recommendation Service that uses purchase history and browsing behavior to personalize the homepage and product pages — typically backed by a feature store and a model serving layer.
• Add an Analytics Pipeline that subscribes to all broker events and feeds a data warehouse for business intelligence.

Security Considerations

At the Container level, security architecture becomes visible:

• The API Gateway is the only container that should be directly reachable from the public internet. Backend services should be on a private network.
• Payment card data should never flow through internal services. The Web Application should tokenize card details directly with Stripe.js before the token reaches the API Gateway, so card numbers are never present in server logs or transit.
• The Admin Application should have a separate authentication policy from the storefront — typically MFA required, separate identity provider configuration, and IP allowlisting for corporate networks.
• The Customer Database is the highest-value target for credential attacks. It should have encryption at rest, column-level encryption for sensitive fields, and strict access controls.

When To Use This Template

Use this template when you need to explain:

• service boundaries and what each service is responsible for
• data ownership and why services should not share databases
• the difference between synchronous checkout flow and asynchronous post-order processing
• where external providers fit into the internal structure and what they replace
• why adding a new downstream consumer of order events does not require changing the Order Service