Skip to content

Commit 78b81fb

Browse files
scottgerringjeastham1993
scottgerring
and
jeastham1993
authored
docs: add sequence diagrams (#8)
Co-authored-by: James Eastham <james.eastham@datadoghq.com>
1 parent 505dcbe commit 78b81fb

4 files changed

Lines changed: 320 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 63 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,48 @@
11
# Stickerlandia
22

3+
![Stickerlandia Logo](https://img.shields.io/badge/Stickerlandia-Collect_and_Trade_Stickers-blue)
4+
[![Documentation](https://img.shields.io/badge/Documentation-Available-green)](./docs/README.md)
5+
6+
## Overview
7+
8+
Stickerlandia lets you collect Datadog stickers by completing Datadog certifications, trading with others, and through various other exciting mechanisms. Users can bring their Stickerlandia account to Datadog events and receive high-quality physical stickers for their gadgets.
9+
10+
This application serves a dual purpose:
11+
12+
- A fun community engagement platform
13+
- A reference application demonstrating modern architectural patterns
14+
15+
As a reference application, Stickerlandia showcases **platform adaptability** by design. We've gone to significant lengths to ensure that all components can be retargeted idiomatically to different platforms - from AWS serverless to Azure Functions to Kubernetes to simple Docker deployments. This adaptability reflects the increasingly common need for applications to run across diverse environments while leveraging each platform's native strengths.
16+
17+
## Key Features
18+
19+
- **Collect stickers** through certifications and achievements
20+
- **Track your collection** of digital stickers
21+
- **Trade stickers** with other community members
22+
- **Redeem physical stickers** at Datadog events
23+
- **Multi-platform deployment** capabilities for cloud and on-premises environments
24+
- **Consistent architecture** across all deployment targets
25+
26+
## Documentation
27+
28+
Comprehensive documentation is available in the [docs](./docs/README.md).
29+
330
## High-Level Architecture
4-
Stickerlandia is built in a microservice fashion, and can run in a bunch of different configurations across various types of modern infrastructure including cloud-native serverless, cloud-native container orchestrated, and self-hosted container orchestrated. In each case, appropriate components are composed together to lean into the strengths of a particular platform - the choice of database, queue technology, and load balancer on a serverless deployment will not be the same as on a self-hosted K8S environment!
531

6-
Services communicate in two ways:
32+
Stickerlandia follows a microservice architecture that can run in various configurations across different types of modern infrastructure:
33+
- Cloud-native serverless
34+
- Cloud-native container orchestration
35+
- Self-hosted container orchestration
736

8-
* Synchronous, RESTful APIs - for both read and write operations, where the operation is naturally imperative. These calls are secured by JWT.
9-
* Asynchronous, event-based APIs - for our implicit, observation based interactions, each service emits business events describing changes in its managed domain.
37+
Each deployment model uses appropriate components optimized for the specific platform - from database selection to queue technology and load balancing. This platform-specific optimization allows Stickerlandia to maintain consistent functionality while leveraging the unique capabilities of each environment.
1038

11-
In both cases these will be modelled in OpenAPI.
39+
## Technical Stack
40+
41+
- **User Management**: .NET-based service for identity and authentication
42+
- **Sticker Award**: Java/Quarkus-based service for sticker management
43+
- **Message Broker**: Kafka or Azure Service Bus for event distribution
44+
- **Databases**: PostgreSQL for structured data
45+
- **Authentication**: JWT-based authentication
1246

1347
## Services
1448

@@ -17,13 +51,30 @@ In both cases these will be modelled in OpenAPI.
1751
| [User Management](./user-management/) | Manages user accounts, authentication, and profile information. Handles user registration, login, and JWT token issuance. | [API Docs](./user-management/docs/api.json) |
1852
| [Sticker Award](./sticker-award/) | Manages the assignment of stickers to users. Tracks which users have which stickers and handles assignment/removal based on criteria like certification completion. | [API Docs](./sticker-award/docs/api.json) |
1953

20-
## Messaging Topics
54+
## Observability
55+
56+
Stickerlandia is fully instrumented with Datadog's observability and analysis tooling, showcasing best practices for modern application monitoring and performance optimization.
57+
58+
## Getting Started
59+
60+
To run Stickerlandia locally, follow these steps:
61+
62+
1. Clone this repository
63+
2. Set up dependencies (see service-specific READMEs)
64+
3. Start the services using Docker Compose or your preferred method
65+
4. Access the application at `http://localhost:8080`
66+
67+
For detailed setup instructions, see the [environment setup guide](./docs/README.md).
68+
69+
> [!NOTE]
70+
> For bigger, more serious microservice architectures, at some point its likely you'll have
71+
> to give up the ability to `docker-compose` your whole stack.
72+
73+
## Contributing
74+
75+
Contributions are welcome! Please see our [contributing guidelines](./CONTRIBUTING.md) for more information.
2176

22-
The following Kafka topics are used for asynchronous communication between services:
77+
## License
2378

24-
| Topic Name | Publishing Service | Description |
25-
|------------|-------------------|-------------|
26-
| users.userRegistered.v1 | User Management | Published when a new user successfully registers. Contains user profile information for other services to initialize user-related data. |
27-
| users.userDetailsUpdated.v1 | User Management | Published when a user updates their profile information. Contains the updated user profile data. |
28-
| users.stickerClaimed.v1 | TODO | TODO |
79+
This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details.
2980

‎docs/README.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Stickerlandia Documentation
2+
3+
This directory contains comprehensive documentation about the Stickerlandia application architecture, including service interactions, event flows, and deployment options.
4+
5+
## Documentation Contents
6+
7+
- [Event Flows](event_flows.md) - Sequence diagrams showing the main event flows between services
8+
9+
## Service Communication
10+
11+
Services in Stickerlandia communicate in two primary ways:
12+
13+
### Synchronous Communication (REST APIs)
14+
15+
- Used for operations requiring immediate responses
16+
- Appropriate for user-facing operations that need immediate feedback
17+
- Examples: user authentication, retrieving user profiles, querying sticker collections
18+
- Implemented as direct HTTP calls between services or from client applications
19+
- Secured using JWT authentication
20+
- API contracts defined in OpenAPI specification
21+
22+
### Asynchronous Communication (Events)
23+
24+
- Used for operations that can be processed in the background
25+
- Appropriate for cross-service notifications and background processes
26+
- Examples: user registration notifications, sticker assignments, certification completions
27+
- Provides system resilience, independent scaling, and reduced service coupling
28+
- Enables critical operations to complete even if dependent services are temporarily unavailable
29+
- Event contracts defined in AsyncAPI specification
30+
31+
The choice between synchronous and asynchronous communication is based on:
32+
- Need for immediate response
33+
- Criticality of the operation
34+
- Number of services that need to be notified
35+
- Fault tolerance requirements
36+
37+
## Message Brokers
38+
39+
Asynchronous communication is implemented using message brokers with support for:
40+
- Kafka - for Kubernetes and self-hosted deployments
41+
- Azure Service Bus - for Azure cloud deployments
42+
43+
## Event Structure
44+
45+
Events follow the CloudEvents specification and include:
46+
- Standard attributes (id, source, type, time)
47+
- Event-specific data payload
48+
- The event data is serialized as JSON
49+
- Topics/channels are named using the pattern: `domain.eventName.version`
50+
51+
## Architecture Overview
52+
53+
Stickerlandia consists of two main services:
54+
55+
1. **User Management Service** (.NET)
56+
- Handles user registration and authentication
57+
- Manages user profiles and credentials
58+
- Issues and validates JWT tokens
59+
- Tracks user sticker statistics
60+
61+
2. **Sticker Award Service** (Java/Quarkus)
62+
- Manages the sticker catalog
63+
- Handles sticker assignments and removals
64+
- Processes certification completions
65+
- Tracks which users own which stickers
66+
67+
## Deployment Options
68+
69+
Stickerlandia supports multiple deployment options:
70+
71+
1. **Serverless Deployment**
72+
- User Management: Azure Functions / AWS Lambda
73+
- Sticker Award: Quarkus with AWS Lambda or Azure Functions
74+
- Messaging: Azure Service Bus / AWS SQS+SNS
75+
- Database: Azure Cosmos DB / AWS DynamoDB
76+
77+
2. **Container Orchestration**
78+
- Kubernetes deployment with Helm charts
79+
- Docker Compose for local development
80+
- PostgreSQL databases with proper persistence
81+
- Kafka for messaging
82+
83+
3. **Local Development**
84+
- Docker Compose setup for all services
85+
- Local PostgreSQL instances
86+
- In-memory or containerized Kafka
87+
88+
## Future Documentation
89+
90+
Additional documentation will include:
91+
92+
- Deployment diagrams
93+
- Data model documentation
94+
- Detailed API documentation
95+
- Environment setup guides
96+
- UI mockups and user flows

‎docs/event_flows.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Stickerlandia Event Flows
2+
3+
This document outlines the event flows between the different services in the Stickerlandia application.
4+
5+
## User Registration Flow
6+
7+
A user can either register directly with Stickerlandia, or login via a federated identity provider. We foresee this to be Datadog's own corporate directory and potentially one associated with our certification provider, so that we can tie external folks' identity up to their awards.
8+
9+
Note: We still need to implement a login interface to facilitate the federated identity integration. This is currently a TODO item for future development.
10+
11+
When a new user registers in the system, the User Management service publishes a user registration event. This flow ensures that other services are aware of new users in the system.
12+
13+
```mermaid
14+
sequenceDiagram
15+
participant Client
16+
participant UserManagement
17+
participant MessageBroker
18+
participant OutboxProcessor
19+
20+
Client->>UserManagement: Register new user
21+
UserManagement->>UserManagement: Create user account
22+
UserManagement->>OutboxProcessor: Store UserRegisteredEvent
23+
UserManagement-->>Client: Registration confirmation
24+
OutboxProcessor->>MessageBroker: Publish users.userRegistered.v1
25+
Note over MessageBroker: Event available for other services
26+
```
27+
28+
## Sticker Assignment
29+
30+
Stickers can be assigned through two primary mechanisms:
31+
1. Via an admin UI, where administrators can manually award stickers to users
32+
2. Via integration with certification systems, where the completion of certifications automatically triggers sticker awards (future state)
33+
34+
For the automatic assignment, another service will adapt external certification events to our internal event model and generate events that the sticker-award service listens to.
35+
Note: This automatic assignment process corresponds to the [Sticker Claimed Flow](#sticker-claimed-flow) described below.
36+
37+
In all cases, the mapping from users to assigned stickers is managed by the sticker-award service.
38+
39+
When a sticker is assigned to a user, the Sticker Award service creates the assignment and notifies other services through events.
40+
41+
```mermaid
42+
sequenceDiagram
43+
participant Client
44+
participant StickerAward
45+
participant Database
46+
participant MessageBroker
47+
participant UserManagement
48+
49+
Client->>StickerAward: POST /api/award/v1/users/{userId}/stickers
50+
StickerAward->>Database: Check if sticker exists
51+
StickerAward->>Database: Check if already assigned
52+
StickerAward->>Database: Create assignment
53+
StickerAward-->>Client: Assignment confirmation
54+
StickerAward->>MessageBroker: Publish stickers.stickerAssignedToUser.v1
55+
MessageBroker->>UserManagement: Consume event
56+
UserManagement->>UserManagement: Update user record
57+
```
58+
59+
## Sticker Removal Flow
60+
61+
Sticker removal is primarily performed through the admin UI, allowing administrators to revoke previously assigned stickers when necessary.
62+
63+
When a sticker is removed from a user, the Sticker Award service updates the assignment status and notifies other services.
64+
65+
```mermaid
66+
sequenceDiagram
67+
participant Client
68+
participant StickerAward
69+
participant Database
70+
participant MessageBroker
71+
participant UserManagement
72+
73+
Client->>StickerAward: DELETE /api/award/v1/users/{userId}/stickers/{stickerId}
74+
StickerAward->>Database: Find active assignment
75+
StickerAward->>Database: Mark as removed
76+
StickerAward-->>Client: Removal confirmation
77+
StickerAward->>MessageBroker: Publish stickers.stickerRemovedFromUser.v1
78+
MessageBroker->>UserManagement: Consume event
79+
UserManagement->>UserManagement: Update user record
80+
```
81+
82+
## Sticker Claimed Flow
83+
84+
This flow represents the scenario where users complete specific challenges or achievements in external systems. A service monitors these achievements and publishes events that inform our system about users qualifying for stickers.
85+
86+
When a user claims a sticker by completing a task or achievement, the event is processed to update the user's account.
87+
88+
```mermaid
89+
sequenceDiagram
90+
participant ExternalSystem
91+
participant MessageBroker
92+
participant UserManagement
93+
participant Database
94+
95+
ExternalSystem->>MessageBroker: Publish users.stickerClaimed.v1
96+
MessageBroker->>UserManagement: Consume via dedicated event worker
97+
UserManagement->>UserManagement: Process StickerClaimedEventV1
98+
UserManagement->>Database: Update user's sticker count
99+
Note over UserManagement: StickerOrdered() method called
100+
```
101+
102+
## Certification Completion Flow
103+
104+
When a user completes a certification in an external system, the Sticker Award service can automatically assign appropriate stickers.
105+
106+
```mermaid
107+
sequenceDiagram
108+
participant CertificationSystem
109+
participant MessageBroker
110+
participant StickerAward
111+
participant Database
112+
113+
CertificationSystem->>MessageBroker: Publish certifications.certificationCompleted.v1
114+
MessageBroker->>StickerAward: Consume event
115+
StickerAward->>Database: Determine appropriate sticker(s)
116+
StickerAward->>Database: Create sticker assignment(s)
117+
StickerAward->>MessageBroker: Publish stickers.stickerAssignedToUser.v1
118+
Note over StickerAward: Automatic award process completed
119+
```

‎docs/messaging_implementation.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Messaging Implementation in Stickerlandia
2+
3+
This document provides details about how the messaging infrastructure is implemented across Stickerlandia services.
4+
5+
## Messaging Technologies
6+
7+
Stickerlandia supports multiple messaging technologies for event-driven communication:
8+
9+
1. **Kafka** - Primary messaging system used for event distribution
10+
1. **Azure Service Bus** - Used for Azure deployments
11+
1. **AWS EventBridge** - Used for AWS deployments
12+
13+
## Event Structure
14+
15+
Events in Stickerlandia follow the CloudEvents specification, which provides a standardized way to describe event data.
16+
17+
```mermaid
18+
classDiagram
19+
class CloudEvent {
20+
String id
21+
URI source
22+
String type
23+
DateTime time
24+
Object data
25+
}
26+
27+
class UserRegisteredEvent {
28+
String eventName = "users.userRegistered.v1"
29+
String eventVersion = "1.0"
30+
String accountId
31+
String toJsonString()
32+
}
33+
34+
class StickerClaimedEventV1 {
35+
String accountId
36+
String stickerId
37+
}
38+
39+
CloudEvent --> UserRegisteredEvent : contains
40+
CloudEvent --> StickerClaimedEventV1 : contains
41+
```
42+

0 commit comments

Comments
 (0)