Skip to content

Latest commit

 

History

History
184 lines (103 loc) · 8.01 KB

events.md

File metadata and controls

184 lines (103 loc) · 8.01 KB
Raw

Events

This document describes each event type that is published by and subscribed by our microservices. Documentating this is important as these are further post-conditions that are manifesting in our system due to business operations.

Each event describes any significant occurance or changes in state for system software. They carry the state (i.e. product purchased, price, customer created) or are identifiers (notification that order has been shipped). The event source can be internal or external inputs, i.e. a user that triggers an new order on a retail website or another of our services notifying us that an order has been shipped. Events are often used to represent facts, i.e. pieces of unchangeable information that is true, for others service to observe.

Events are published on our message/event broker Apache Kafka. Each event is published on a specific topic that is named like the entity for which said event is published, i.e. customer for all customer events. It is important that every event type, even different event types, that are for a specific entity are published on the same topic. This makes sure that the events keep the ordering in which they have occured in our system. Publishing CustomerCreatedEvents on a customer-created topic and CustomerDeletedEvents on a customer-deleted topic could lead to the fact that a microservice would first process a CustomerDeletedEvent instead of the CustomerCreatedEvent for that customer, which makes is semantically nonsense as no customer can be deleted if it has not existed before.

Each event schema is described in the appropriate Avro Schema files, see ./avro. If you are interested in what data each event contains, please look inside the schema files for the latest definition. Which is also the only one that is correct as through these Avro Schema files the classes will be auto-generated by the Apache Avro compiler.

The following list describes every existing event in our system. It will highlight what intent the specific event is trying to express, which services produce such events and which services consume such events and why they would consume such events. Furthermore, each of the following events is only published after a transaction to the service database has been committed successfully. That also means that if the event could not be published, e.g. an exception because the broker could not be reached, the transaction will be rollbacked.

Customer related events

CustomerCreatedEvent

Intent

Signal to subscribers that a new customer has created themselves an account for our shop.

Publisher

Produced by:

  • CustomerService as a reaction to a HTTP POST request on /customers with a JSON body containing the details for said customer.

Subscriber

Consumed by:

  • OrderService: To persist the IDs of each created customer to permit only valid customerIds during the creation of an order entity without having to interact again with the CustomerService.
  • BusinessIntelligenceService: To add the age of the created customer to the histogram that is used to analyse which customer age groups are creating accounts on the shop, i.e. maybe improve marketing/available products etc.

CustomerDeletedEvent

Intent

Signal to subscribers that a customer has deleted their account.

Publisher

Produced by:

  • CustomerService as a reaction to a HTTP DELETE request on /customers/{id}.

Subscriber

Consumed by:

  • OrderService: To remove the id of said customer and perform a cascading delete on all their orders.
  • BusinessIntelligenceService: To remove the age from the deleted customers from the histogram that is used to analyse which customer age groups are having accounts on the shop.

CustomerUpdatedEvent

Intent

Signal to subscribers that a customer has changed their account information.

Publisher

Produced by:

  • CustomerService as a reaction to a HTTP PUT request on /customers/{id} with a JSON body containing information that needs to be changed.
  • NOT YET IMPLEMENTED: CustomerService could perform daily checks if the age (based on the given birthday) of a specific customer needs to be incremented.

Subscriber

Consumed by:

  • BusinessIntelligenceService: To change the age of the updated customer in the histogram that is used to analyse which customer age groups are having accounts on the shop.

Product related events

A ProductRemovedEvent does not exist. This is due to the fact that the shop wants to provide an "order" audit log from which can be seen which products have been bought by whom. To do so in an fashion that is future-proof, we are not deleting products from the ProductCommandService/ProductQueryService and its database.

In a system with more allocated development time, products should be soft-deleted.

ProductAddedEvent

Intent

Signal to subscribers that a new product has been added to the warehouse.

Publisher

Produced by:

  • ProductCommandService as a reaction to HTTP POST request on /products with a JSON body containing the details for said product.

Subscriber

Consumed by:

  • OrderService: To persist the IDs of each added product to permit only valid productIds during the creation of an order entity without having to interact again with the ProductCommandService/ProductQueryService.
  • ProductQueryService: To persist the newly added product in memory so it is available through the query interface

ProductUpdatedEvent

Intent

Signal to subscribers that a product's information has been updated.

Publisher

Produced by:

  • ProductCommandService as a reaction to a HTTP PUT request on /products/{id} with a JSON body containing the changes to said product.

Subscriber

  • ProductQueryService: To persist the newly added product in memory so it is available through the query interface

Order related events

OrderCreatedEvent

Intent

Signal to subscribers that a customer has placed an order (created a new order) for a specific product.

Publisher

Produced by:

  • OrderService as a reaction to a HTTP POST request on /orders with a JSON body containing the details to said product.

Subscriber

Consumed by:

  • BusinessIntelligenceService: To add the productId of the placed order to the histograms which are used to perform an market analysis for our products that shows how many customers were interested in which product and how many products have been bought.

OrderDeletedEvent

Intent

Signal to subscribers that a customer has deleted their order.

Publisher

Produced by:

  • OrderService as a reaction to a HTTP DELETE request on /orders/{id}.

Subscriber

Consumed by:

  • BusinessIntelligenceService: To delete the productId of the placed order from the histograms which are used to perform an market analysis for our products that shows how many customers were interested in which product and how many products have been bought.

OrderUpdatedEvent

Intent

Signal to subscribers that an order has been update, i.e. either the products of said order have been changed or its status has been changed (i.e. from PLACED to PAID)

Publisher

Produced by:

  • OrderService as a reaction to a HTTP PUT request on /orders/{id} with a JSON body containing the fields that need to be changed.
  • OrderService as a reaction to a HTTP PUT request on /orders/{id}/{pay,ship,deliver,cancel} to change the status of this order into {PAID, SHIPPED, DELIVERED, CANCELLED}
  • NOT YET IMPLEMENTED: The OrderService would receive notifications from external systems if the products of a specific order are shipped or delivered, i.e. a shipping company like DHL would supply us with such a notifcation.

Subscriber

Consumed by:

  • BusinessIntelligenceService: To check if the productId of this order needs to be added/removed from the histograms which are used to perform an market analysis for our products that shows how many customers were interested in which product and how many products have been bought.