Microservice-architecture.md

+This document is a work in progress documenting architectural choices made for Velox shop.
+
+Microservice in Velox shop
+--------------------------
+### Principles
+1. Single purpose
+    Each service service should focus on single function and do it well.
+2. Lose coupling
+    Direct strict dependencies between services should be avoided.
+3. High cohesion
+    Each service should be standalone and self contained.
+
+### Requirements
+1. No shared databases.
+2. Token based shared authentication.
+
+<!-- ### Decoupling building service from running service
+
+### Observability -->
+
+Inter-service communication
+--------------------------------
+### Interaction approach
+Different approaches for services communication can be applied. Most common ones were considered.
+**We decided to apply the orchestration model with central integration point.**
+
+#### Direct interaction
+Service can communicate directly with any other service to fulfill own duty.
+```mermaid
+sequenceDiagram
+Participant User
+Participant Frontend
+User ->>+Frontend : add item\n to cart
+Frontend ->>+ Cart service : add item\n to cart
+Cart service ->>+ Product service : request required\n product data
+Product service -->>- Cart service : return product\n data
+Cart service ->>+ Stock service : request stock data
+Stock service -->>- Cart service : return stock data
+Cart service -->>- Frontend : return operation\n result
+Frontend -->>- User : display operation\n confirmation
+```
+Pros:
+* easy approach
+* SOA like implementation
+
+Cons:
+* High coupling and low cohesion
+* API dependencies between services
+* effectively distributed-monolithic application
+
+#### Orchestration model with central integration point
+Integration point(s) is responsible to gather and compose all resources for given workflow.
+```mermaid
+sequenceDiagram
+Participant User
+Participant Frontend
+Participant integration as Integration <br /> Point
+Note over Frontend, integration : Both can be <br/> single application
+User ->>+Frontend : add item\n to cart
+Frontend ->>+ integration : add item\n to cart
+integration ->>+ Product service : request required\n product data
+Product service -->>- integration : return product\n data
+integration ->>+ Stock service : request stock data
+Stock service -->>- integration : return stock data
+integration ->>+ Cart service : add item to cart passing required product data
+Cart service -->>- integration : return operation\n result
+integration -->>- Frontend : return operation\n result
+Frontend -->>- User : display operation\n confirmation
+```
+Pros:
+* full decoupling of services
+* ease of service change - only integration point potentially affected
+* no service dependency allow integration of any service alone in new projects
+
+Cons:
+* potential performance bottleneck
+* business logic may leak to workflow (integration point) leading to fat implementation
+
+##### Service bus or workflow engine
+Distinct functional aspects can be separated in different integration points, eg. checkout integration.
+Workflows can be also implemented serverless, eg. as AWS Lambda functions.
+
+##### Direct integration in client
+Services can be accessed directly from client.
+
+#### No inter-service interaction (event driven asynchronous replication)
+All services must store data needed for their operation. Replication is based on change announcements published by data source service. Other services listen to those events and update their copies.
+```mermaid
+sequenceDiagram
+Participant User as User / FE
+Participant PIM
+Participant ERP integration
+Participant mb as Message bus
+Participant cart as Cart service
+Participant cartStore as Cart service <br /> persistence
+PIM ->> mb : product update publication
+mb -->> cart : retrieves updated product data
+cart -->> cartStore : store relevant product data
+ERP integration ->> mb : stocks update publication
+mb -->> Stock service : retrieves updated stock data
+Stock service -->> Stock service persistence : store stock data
+mb -->> cart : retrieves updated stock data
+cart -->> cartStore : store relevant stock data
+User ->>+ Stock service : get stock data
+Stock service ->> Stock service persistence : get stock data
+Stock service -->>- User : return stock data
+User ->>+ cart : add item to cart
+cart ->> cartStore : get cart data
+cart ->> cartStore : get prduct data
+cart ->> cartStore : get stock data
+cart ->> cartStore : save updated cart
+cart -->>- User : return operation result
+```
+Pros:
+* high decoupling with high cohesion
+* high availability - even when source service is not available dependent service can perform it's duty based on stored copy of data
+
+Cons:
+* consistency issues - application must tolerate eventually consistent data and compensations need to be utilized to provide transactions/rollbacks.
+
+<!-- ##### Messaging -->
+
+### Consistency handling
+#### Keeping transactional updates within one service
+If possible avoid cross-service updates. Be aware that this approach can be against general principle thus not always feasible solution.
+
+#### Compensation and use of other guarantees
+Work without service cross-boundary transaction. Work in parallel and explicitly compensate for any errors.
+```mermaid
+sequenceDiagram
+Participant User
+Participant ip as Integration Point
+User ->>+ ip : place order
+ip ->> Payment service : take payment
+ip ->>+ Order service : place order
+alt order placed
+Order service ->> ip : order confirmed
+else order failure
+Order service ->>- ip : order cancelled
+ip ->> Payment service : refund payment
+end
+ip ->>- User : return operation result
+```
+
+### Protocol choices
+Services are exposed for Frontend using REST interface. Integration point-service protocol yet to be established.
+
+#### RPC
+Modern RPC protocol over HTTP2 developed by Google.
+
+More info: [gRPC](https://grpc.io)
+
+#### REST
+Also REST can be applied.
+
+<!-- ### Contract approaches
+#### API approach
+#### Message approach -->
+
+<!-- Security
+--------
+### JWT token solution -->