# datadog/serverless-sample-app architecture

> Architecture diagram of the GitHub repository datadog/serverless-sample-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datadog/serverless-sample-app
- Repository: https://github.com/datadog/serverless-sample-app

## Overview

1. This repository is a polyglot, multi-service serverless demo application focused on observability. The architecture is intentionally event-driven: user actions enter through HTTP APIs, state is stored in service-owned datastores, and cross-service behavior is coordinated through asynchronous events and workflows.

2. The repo is organized as a set of mostly independent bounded contexts under `src/`, each with its own runtime code, infrastructure definition, tests, and API/event contracts. The same logical service is often implemented in multiple IaC styles or runtimes, but the architectural shape stays consistent: API entrypoint, background/event consumers, private persistence, and published domain events.

3. `src/shared-infra` provides common cloud resources used by multiple services, especially shared secrets and platform bootstrap resources. At the top level, the repo also includes GitHub Actions workflows for per-service deploys and static analysis, plus a `build-image` path that packages the tooling needed to deploy the whole system.

4. `src/frontend` is a thin browser UI. It does not own business state; it calls the backend service APIs generated into a local config file and is used to exercise login, catalog browsing, order flows, and admin operations.

5. `src/user-management-service` owns identity and user profiles. It exposes registration, login, and user-detail endpoints, issues JWTs consumed by other services, and listens for order events to update a user’s order-related state. The service is split into an API surface and background/event-processing lambdas, with shared observability code for tracing.

6. `src/product-management-service` owns the product catalog. It provides CRUD/query APIs for products, publishes public product events, and reacts to downstream changes such as stock and pricing updates. The codebase is split into a product API, a product ACL for translating external events, and an event publisher component for domain events.

7. `src/inventory-service` owns stock levels and reservation logic. It exposes inventory management APIs, persists inventory state, and consumes product and order events through an anti-corruption layer. It emits inventory and reservation outcome events that other services use to keep catalog and order state consistent.

8. `src/order-service` owns order creation and fulfillment. The API handles create/complete/query operations, while a separate background worker and Step Functions workflow manage the asynchronous order-processing lifecycle. It publishes order lifecycle events and consumes inventory reservation outcomes, making it the clearest example of choreography plus orchestration in the repo.

9. `src/loyalty-point-service` manages loyalty accounts and tier progression. The API handles point lookup and spending, event handlers react to user and order events, and a dedicated tier workflow computes tier upgrades using other services as inputs. This service demonstrates both transactional point updates and longer-running workflow orchestration.

10. `src/pricing-service` computes custom pricing for eligible users. It exposes a pricing calculation API and also reacts to product catalog changes so derived prices stay current. Its handlers, adapters, and event publisher are separated so pricing can be reused both synchronously and asynchronously.

11. `src/activity-service` is a smaller Python service that records and reads activity data. Architecturally it follows the same pattern as the others: Lambda handlers at the edge, a logic layer, a DynamoDB-backed DAL, and utility code for idempotency and observability.

12. Several services include an explicit anti-corruption layer or adapter boundary. That boundary translates between external event schemas, internal domain models, and transport-specific wrappers, which is important for any diagram because most inter-service coupling is through events rather than direct database or code sharing.

13. The platform uses AWS-native managed services as the core integration fabric: API Gateway for synchronous requests, Lambda for compute, DynamoDB for service-owned persistence, EventBridge/SNS/SQS-style messaging for asynchronous propagation, and Step Functions where a workflow needs explicit sequencing. The architecture is therefore loosely coupled, with clear write ownership per service and fan-out through events.

14. Observability is a first-class cross-cutting concern rather than an afterthought. The sample emphasizes Datadog tracing, span links, and data-streams monitoring across synchronous API calls and asynchronous message hops, and the repo includes service-specific observability packages plus generated docs/contracts for event schemas and APIs.

15. The `api-docs` and per-service `docs/` folders are part of the architecture, not just documentation. They define the event catalog, OpenAPI/AsyncAPI shapes, and domain/service contracts that mirror the runtime boundaries and are useful for drawing the system diagram accurately.

16. Supporting pieces include `loadtest` for traffic generation, `demo-reset-service` for reseeding and cleanup, and `order-mcp` as an auxiliary MCP-oriented integration surface. These are not the core business flow, but they matter as operational and demo-support subsystems.

Main entry points: [`src/order-service`](https://github.com/datadog/serverless-sample-app/tree/main/src/order-service) (Orders), [`src/product-management-service`](https://github.com/datadog/serverless-sample-app/tree/main/src/product-management-service) (Products), [`src/frontend`](https://github.com/datadog/serverless-sample-app/tree/main/src/frontend) (Frontend), [`src/pricing-service`](https://github.com/datadog/serverless-sample-app/tree/main/src/pricing-service) (Pricing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_repo["Repo"]
  node_shared_infra[("Shared infra<br/>cloud bootstrap")]
  node_api_docs["API docs<br/>contracts"]
  node_ci_cd["CI/CD<br/>workflows<br/>[workflows]"]
  node_build_image["Build image<br/>tooling image"]
  node_observability(("Observability<br/>cross-cutting"))
end

subgraph group_apps["Services"]
  node_frontend["Frontend<br/>browser ui"]
  node_user_mgmt{{"Users<br/>identity service"}}
  node_product_mgmt{{"Products<br/>catalog service"}}
  node_inventory{{"Inventory<br/>stock service"}}
  node_orders{{"Orders<br/>order service"}}
  node_loyalty{{"Loyalty<br/>points service"}}
  node_pricing{{"Pricing"}}
  node_activity{{"Activity"}}
  node_product_search{{"Search"}}
end

subgraph group_support["Support"]
  node_order_mcp["Order MCP<br/>aux integration"]
  node_demo_reset["Resetter<br/>ops service"]
  node_loadtest["Load test<br/>traffic gen"]
end

node_repo -->|"shared bootstrap"| node_shared_infra
node_repo -->|"contracts"| node_api_docs
node_repo -->|"automation"| node_ci_cd
node_repo -->|"tooling"| node_build_image
node_repo -->|"ui"| node_frontend
node_repo -->|"service"| node_user_mgmt
node_repo -->|"service"| node_product_mgmt
node_repo -->|"service"| node_inventory
node_repo -->|"service"| node_orders
node_repo -->|"service"| node_loyalty
node_repo -->|"service"| node_pricing
node_repo -->|"service"| node_activity
node_repo -->|"service"| node_product_search
node_repo -->|"surface"| node_order_mcp
node_repo -->|"ops"| node_demo_reset
node_repo -->|"load"| node_loadtest
node_user_mgmt -.->|"user events"| node_orders
node_product_mgmt -.->|"product events"| node_inventory
node_inventory -.->|"reservation outcomes"| node_orders
node_orders -.->|"order events"| node_loyalty
node_orders -.->|"order events"| node_inventory
node_product_mgmt -.->|"catalog events"| node_pricing
node_pricing -.->|"price updates"| node_product_mgmt
node_loyalty -.->|"tier/user updates"| node_user_mgmt
node_pricing -.->|"pricing lookup"| node_orders
node_product_search -.->|"catalog sync"| node_product_mgmt
node_frontend -->|"auth api"| node_user_mgmt
node_frontend -->|"catalog api"| node_product_mgmt
node_frontend -->|"order api"| node_orders
node_frontend -->|"points api"| node_loyalty
node_frontend -->|"pricing api"| node_pricing
node_activity -.->|"tracing"| node_observability
node_user_mgmt -.->|"tracing"| node_observability
node_product_mgmt -.->|"tracing"| node_observability
node_inventory -.->|"tracing"| node_observability
node_orders -.->|"tracing"| node_observability
node_loyalty -.->|"tracing"| node_observability
node_pricing -.->|"tracing"| node_observability
node_product_search -.->|"tracing"| node_observability

click node_shared_infra "https://github.com/datadog/serverless-sample-app/tree/main/src/shared-infra"
click node_api_docs "https://github.com/datadog/serverless-sample-app/tree/main/api-docs/event-catalog"
click node_ci_cd "https://github.com/datadog/serverless-sample-app/blob/main/.github/workflows"
click node_build_image "https://github.com/datadog/serverless-sample-app/tree/main/build-image"
click node_frontend "https://github.com/datadog/serverless-sample-app/tree/main/src/frontend"
click node_user_mgmt "https://github.com/datadog/serverless-sample-app/tree/main/src/user-management-service"
click node_product_mgmt "https://github.com/datadog/serverless-sample-app/tree/main/src/product-management-service"
click node_inventory "https://github.com/datadog/serverless-sample-app/tree/main/src/inventory-service"
click node_orders "https://github.com/datadog/serverless-sample-app/tree/main/src/order-service"
click node_loyalty "https://github.com/datadog/serverless-sample-app/tree/main/src/loyalty-point-service"
click node_pricing "https://github.com/datadog/serverless-sample-app/tree/main/src/pricing-service"
click node_activity "https://github.com/datadog/serverless-sample-app/tree/main/src/activity-service"
click node_product_search "https://github.com/datadog/serverless-sample-app/tree/main/src/product-search-service"
click node_order_mcp "https://github.com/datadog/serverless-sample-app/tree/main/src/order-mcp"
click node_demo_reset "https://github.com/datadog/serverless-sample-app/tree/main/src/demo-reset-service"
click node_loadtest "https://github.com/datadog/serverless-sample-app/tree/main/loadtest"

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_repo,node_shared_infra,node_api_docs,node_ci_cd,node_build_image,node_observability toneBlue
class node_frontend,node_user_mgmt,node_product_mgmt,node_inventory,node_orders,node_loyalty,node_pricing,node_activity,node_product_search toneAmber
class node_order_mcp,node_demo_reset,node_loadtest toneMint
```

## Components

### Platform

Repo-wide tooling, shared infra, and contracts

- **Repo**: monorepo · Polyglot serverless demo application
- [Shared infra](https://github.com/datadog/serverless-sample-app/tree/main/src/shared-infra): cloud bootstrap · Common secrets and bootstrap resources used by multiple services · `src/shared-infra`
- [API docs](https://github.com/datadog/serverless-sample-app/tree/main/api-docs/event-catalog): contracts · OpenAPI, AsyncAPI, and event catalog definitions · `api-docs/event-catalog`
- [CI/CD](https://github.com/datadog/serverless-sample-app/blob/main/.github/workflows): workflows · GitHub Actions for deploys, analysis, and image builds · `.github/workflows`
- [Build image](https://github.com/datadog/serverless-sample-app/tree/main/build-image): tooling image · Containerized build and deploy tooling · `build-image`
- **Observability**: cross-cutting · Datadog tracing, span links, and data-streams instrumentation across services

### Services

Business services and the thin frontend

- [Frontend](https://github.com/datadog/serverless-sample-app/tree/main/src/frontend): browser ui · Thin UI that exercises auth, catalog, order, and admin flows · `src/frontend`
- [Users](https://github.com/datadog/serverless-sample-app/tree/main/src/user-management-service): identity service · Registration, login, profiles, JWT issuance, and order-driven user updates · `src/user-management-service`
- [Products](https://github.com/datadog/serverless-sample-app/tree/main/src/product-management-service): catalog service · Product CRUD, public product events, and downstream change handling · `src/product-management-service`
- [Inventory](https://github.com/datadog/serverless-sample-app/tree/main/src/inventory-service): stock service · Stock levels, reservations, and inventory outcome events · `src/inventory-service`
- [Orders](https://github.com/datadog/serverless-sample-app/tree/main/src/order-service): order service · Order lifecycle API plus background workflow orchestration · `src/order-service`
- [Loyalty](https://github.com/datadog/serverless-sample-app/tree/main/src/loyalty-point-service): points service · Points, tier progression, and workflow-based upgrades · `src/loyalty-point-service`
- [Pricing](https://github.com/datadog/serverless-sample-app/tree/main/src/pricing-service): pricing service · Derived pricing API and catalog-driven recalculation · `src/pricing-service`
- [Activity](https://github.com/datadog/serverless-sample-app/tree/main/src/activity-service): activity service · Small Python service for recording and reading activity data · `src/activity-service`
- [Search](https://github.com/datadog/serverless-sample-app/tree/main/src/product-search-service): search service · Product search indexing and query service · `src/product-search-service`

### Support

Demo and operational support components

- [Order MCP](https://github.com/datadog/serverless-sample-app/tree/main/src/order-mcp): aux integration · Auxiliary MCP-oriented integration surface for order/product access · `src/order-mcp`
- [Resetter](https://github.com/datadog/serverless-sample-app/tree/main/src/demo-reset-service): ops service · Reseeds and clears demo data · `src/demo-reset-service`
- [Load test](https://github.com/datadog/serverless-sample-app/tree/main/loadtest): traffic gen · Workload generators and scenarios for demo stress testing · `loadtest`

## Connections

- Repo → Shared infra: shared bootstrap · Common cloud resources and secrets
- Repo → API docs: contracts · System API and event schemas
- Repo → CI/CD: automation · Deploy and analysis workflows
- Repo → Build image: tooling · Build/deploy image packaging
- Repo → Frontend: ui · Browser client
- Repo → Users: service · Identity bounded context
- Repo → Products: service · Catalog bounded context
- Repo → Inventory: service · Stock bounded context
- Repo → Orders: service · Order bounded context
- Repo → Loyalty: service · Loyalty bounded context
- Repo → Pricing: service · Derived pricing bounded context
- Repo → Activity: service · Activity capture service
- Repo → Search: service · Search/index service
- Repo → Order MCP: surface · Auxiliary MCP integration
- Repo → Resetter: ops · Demo reset and reseed
- Repo → Load test: load · Traffic generation scenarios
- Users → Orders: user events · User profile and order-related updates
- Products → Inventory: product events · Catalog changes consumed by stock management
- Inventory → Orders: reservation outcomes · Inventory reservation success/failure events
- Orders → Loyalty: order events · Completed order events drive points and tier updates
- Orders → Inventory: order events · Order creation feeds reservation logic
- Products → Pricing: catalog events · Product changes refresh derived pricing
- Pricing → Products: price updates · Updated pricing feeds product state
- Loyalty → Users: tier/user updates · Loyalty workflows use user data and emit point/tier outcomes
- Pricing → Orders: pricing lookup · Orders can consult computed pricing
- Search → Products: catalog sync · Search index follows product catalog changes
- Frontend → Users: auth api · Registration and login calls
- Frontend → Products: catalog api · Browse and admin catalog calls
- Frontend → Orders: order api · Create, complete, and query order flows
- Frontend → Loyalty: points api · User loyalty lookup and spending
- Frontend → Pricing: pricing api · Pricing calculation entrypoint
- Activity → Observability: tracing · Shared telemetry and idempotency patterns
- Users → Observability: tracing · Shared telemetry and span propagation
- Products → Observability: tracing · Cross-service telemetry and event links
- Inventory → Observability: tracing · Datadog instrumentation across async hops
- Orders → Observability: tracing · Workflow and message tracing
- Loyalty → Observability: tracing · API and workflow instrumentation
- Pricing → Observability: tracing · Pipeline checkpointing and telemetry
- Search → Observability: tracing · Messaging observability