datadog/serverless-sample-app

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.