eloquenza / favs-project-event-driven-services Goto Github PK

A document on how to use, interact, start or develop this software is needed. It should atleast contain the following topics:

• How to compile
• How to start
• What software is needed prior to start/compile (i.e. software requirements like maven, java, ...)

Currently there is a lack of code documentation because this project was hacked together very quickly.
We should add a bit of commentary, esp. to code parts with high (technical) impact.

We might need to remove all TODOs from the comments if the professor would like so. This issue exists purely to track this.

Currently, our REST API route naming scheme consists of:

/$resource-plural/v1/$resource-plural/{create, id}

This allows us to implement other versions and use the Spring Cloud Gateway to route the requests to the appropriate microservices.

Research some renown, widely used REST APIs on how they implement a consistent naming scheme, esp. considering versioning.

Some ideas:

• URI versioning is fine, but not in the currently naming scheme, maybe use:
  /$resource-management/v1/$resource-plural/{create, id}
• Implement some MIME type versioning, i.e. clients/server use a header like Accept: application/favs.commerce.customer.v1+json

Currently, most of the POMs are very copy-paste due to the fast velocity of this project.
Extracting some of the dependencies and plugins into the parent POM makes this whole project more wieldable, and all children POMs more readable/configurable/handable/understandable.

Currently, we have no form of CQRS in our system. To achieve this, some/all microservices need to be split into a command and a query part.

If we are not splitting all microservices because of some reason, we should first document that reason and explain why only some services have been split.

The following two would be a good idea to split at the least: CustomerService and ProductService.

The document/diagrams should explain how Event Sourcing and Command Query Responsibility Segregation are used exactly and what they enable (code/technical-wise).
For example, this could showcase a sequence diagram on what happens when a user is creating his own account in our system, i.e. which services are interacting together, how does CQRS / ES help here.

Either in some form of an architecture.md [0] or ADRs [1].

[0] https://www.reddit.com/r/programming/comments/le46br/why_you_need_architecturemd/
[1] https://en.wikipedia.org/wiki/Architectural_decision

Create an document that describes how to interact with our system once it is started. It should atleast contain:

• describing business use case
• showcasing a few business work flows
• define how to interact with the system: provide cURL / Shell scripts and show how to use GUI.
• Write down that it is possible, that certain services might need a while before they are available. Docker-compose creating ... done does not mean, the service is started and reachable. Even after the log output ends, the gateway might need a while for the routing of requests -> concrete services takes hold.

Does not mean, that the service has crashed, only that it is currently unavailable due to routing of gateway being to slow (might a be local/machine thing, due to constrainted resources available).
{ "timestamp": 1615409020742, "path": "/customers", "status": 503, "error": "Service Unavailable", "message": "", "requestId": "fa12285a-1" }

Currently, the schema registration is handled through maven, where I am pressing it manually in my IDE whenever I am testing the system.

Provide a way to set up the schema registration either outside of Maven or look into a way to use the current way inside the docker-compose step.

Currently, the database schemes are only informally described in our changelog.yamls.

A small document showcasing all database schemes could help understand the system better.

The CustomerService does not follow our folder structure convention

Here, Kafka was not starting up due to Zookeeper not being ready.
Write a depends_on order in docker-compose in order to avoid this bug.

Currently, we only have create and retrieve (the C and R in CRUD) functionality for our entities (only R for product).

The other basic operations of managing and interacting with data should be implemented, too.

• deleteCustomer
• updateCustomer
• deleteOrder
• updateOrder

Atleast for the customer and order entities.
We could declare that our product entities are managed by some other form, i.e. an internal system which an warehouse worker uses to enter new products.

Extracting the fixed logic from the CustomerService, moving it into a parent module and generalizing it into a reusable function allows us to make sure every CRUD operation + event emission on any entity will be handled in the same way.

Currently, we need to write an MessageConverter for each Message.
Which does not seem appropriate considering the fact that this is a 1:1 relationship, i.e. for each event we need to write a new MessageConverter, which simply bloats amount of classes.
Ideally we would convert all our events back to simple POJOs, as Spring Cloud Stream seems to be able to convert these without problems from/to JSON.
But this does seem a bit backwards, as there definitely should be an easier way for this.

Find better way for converting events <-> json to avoid having to write an converter for each event.