Add other ADRs

Author: kgrzybek

docs/architecture-decision-log/0005-create-one-rest-api-module.md

@@ -0,0 +1,45 @@
+# 5.   Create one REST API module
+
+Date: 2019-07-01
+
+Log date: 2019-11-04
+
+## Status
+
+Accepted
+
+## Context
+
+We need to expose the API of our application to the outside world. For now, we expect one client of our application - FrontEnd SPA application.
+
+## Possible solutions
+1. Create one .NET Core MVC host application which contains all endpoints. This host application will have references to all business modules and communicates with them directly:</br>
+
+Host/API references:</br>
+Administration module</br>
+Meetings module</br>
+Payments module</br>
+User Access module</br>
+
+2. Create one .NET Core MVC host application and multiple APIs projects per module. Each API project should have endpoints which are handled by particular business module:</br> 
+
+Host references:</br>
+Administration API references Administration module</br>
+Meetings API references Meetings module</br>
+Payments API references Payments module</br>
+User Access API references User Access module</br>
+
+## Decision
+
+Solution 1.
+
+Creating separate API projects for each module will add complexity and little value. Grouping endpoints for a particular business module in a special directory is enough. Another layer on top of the module is unnecessary.
+
+## Consequences
+- We will have only one API layer/module
+- Each controller has responsibility to delegate Command/Query processing to appropriate module
+- We don't need to scan other projects than host for controllers, routes and other MVC mechanisms
+- API configuration is easier
+- Overall complexity of API layer is lower
+- Complexity of each controller is a little bit higher
+- Build time will be shorter (less projects)

docs/architecture-decision-log/0006-create-facade-between-api-and-business-module.md

@@ -0,0 +1,33 @@
+# 6. Create façade between API and business module
+
+Date: 2019-07-01
+
+Log date: 2019-11-04
+
+## Status
+
+Accepted
+
+## Context
+
+Our API layer should communicate with business modules to fulfill client requests. To support the maximum level of autonomy, each module should expose a minimal set of operations (the module API/contract/interface).
+
+## Decision
+
+Each module will provide implementation for one interface with 3 methods:</br>
+
+```csharp
+Task<TResult> ExecuteCommandAsync<TResult>(ICommand<TResult> command);
+
+Task ExecuteCommandAsync(ICommand command);
+
+Task<TResult> ExecuteQueryAsync<TResult>(IQuery<TResult> query);
+```
+
+This interface will act as a façade (Façade pattern) between API and module. Only Commands, Queries and returned objects (which are part of this interface) should be visible to the API. Everything else should be hidden behind the façade (module encapsulation).
+
+## Consequences
+- API can communicate with the module only by façade (the interface).
+- Implementation of API is simpler
+- We can change module implementation and API does not require change if the interface is not changed
+- We need to focus on module encapsulation, sometimes it involves additional work (like instantiation using internal constructors)

docs/architecture-decision-log/0007-use-cqrs-architectural-style.md

@@ -0,0 +1,28 @@
+# 7. Use CQRS architectural style
+
+Date: 2019-07-01
+
+Log date: 2019-11-04
+
+## Status
+
+Accepted
+
+## Context
+
+Our application should handle 2 types of requests - reading and writing. </br>
+
+For now, it looks like:</br>
+
+- for reading, we need data model in relational form to return data in tabular/flattened way (tables, lists, dictionaries).
+- for writing, we need to have a graph of objects to perform more sophisticated work like validations, business rules checks, calculations.
+
+## Decision
+
+We applied the CQRS architectural style/pattern for each business module. Each module will have a separate model for reading and writing. For now, it will be the simplest CQRS implementation when the read model is immediate consistent. This kind of separation is useful even in simple modules like User Access.
+
+## Consequences
+- Façade method of each module should take as parameter only Command or Query object
+- We have optimized models for writes and reads (SRP principle).
+- We can process Commands and Queries in different ways
+- As Command or Query is an object, we can easily serialize them and save/log them.

docs/architecture-decision-log/0008-allow-return-result-after-command-processing.md

@@ -0,0 +1,23 @@
+# 8. Allow return result after command processing
+
+Date: 2019-07-01
+
+Log date: 2019-11-04
+
+## Status
+
+Accepted
+
+## Context
+
+The theory of the CQRS and the CQS principle says that we should not return any information as the result of Command processing. The result should be always "void". However, sometimes we need to return some data immediately as part of the same request.
+
+## Decision
+
+We decided to allow in some cases return results after command processing. Especially, when we create something and we need to return the ID of created object or don't know if request is Command or Query (like Authentication).
+
+## Consequences
+- We will have two definitions of Commands and CommandHandlers - with and without result
+- It will add some complexity to processing commands (like implementation of decorators)
+- We can immediately return the ID of created object/resource. We don't need a second call (query) to retrieve this ID.
+- We should be careful to not overuse this approach (sticking as much as possible to the CQRS)

docs/architecture-decision-log/0009-use-2-layered-architectural-style-for-reads.md

@@ -0,0 +1,24 @@
+# 9. Use 2 layered architectural style for reads
+
+Date: 2019-07-01
+
+Log date: 2019-11-04
+
+## Status
+
+Accepted
+
+## Context
+
+We applied the CQRS style (see [ADR 7. Use CQRS architectural style](007-use-cqrs-architectural-style.md)), now we need to decide how to handle reading (querying) requests.
+
+## Decision
+
+We will use 2 layered architecture to handle queries: API layer and Application Service layer. As we applied the CQRS and created a separated read model, querying should be straightforward so 2 layers are enough. The API layer is responsible for Query creation based on HTTP request and the module Application layer is responsible for query handling.
+
+## Consequences
+- Whole query handling logic is in Application Service layer
+- Application Service layer is coupled to the database and querying framework
+- Solution is simple, easy to understand
+- We don't abstract over database
+- Performance is better (no object mapping between layers, querying database almost immediately)

docs/architecture-decision-log/0010-use-clean-architecture-for-writes.md

@@ -0,0 +1,28 @@
+# 10. Use Clean Architecture for writes
+
+Date: 2019-07-01
+
+Log date: 2019-11-05
+
+## Status
+
+Accepted
+
+## Context
+
+We applied the CQRS style (see [ADR 7. Use CQRS architectural style](007-use-cqrs-architectural-style.md)), now we need to decide how to handle writing operations (Commands).
+
+## Decision
+
+We will use **Clean Architecture** to handle commands with 4 layers: **API layer**, **Application Service layer** **Infrastructure layer** and **Domain layer**. </br>
+We need to add Domain layer because domain logic will be complex and we want to isolate this logic from other stuff like infrastructure or API. Isolation of domain logic supports testing, maintainability and readability.
+
+## Consequences
+- Complexity of the whole solution is higher - we need to add two more layers - domain and infrastructure
+- Complexity of implementation of business logic will be smaller - we can focus only on business concerns on this layer
+- Complexity of implementation of infrastructure will be smaller - we can focus only on infrastructure concerns on this layer
+- Business logic will be testable (no references to other layers)
+- Business logic will be independent of persistence (to some level)
+- In the Domain layer, we will have the same level of abstraction (close to business)
+- Application layer will have louse coupling to the Domain layer and Infrastructure layer (depend  on abstractions only)
+- We use one of the most popular application architecture - developers are familiar with it

docs/architecture-decision-log/0011-create-rich-domain-models.md

@@ -0,0 +1,37 @@
+# 11. Create rich Domain Models
+
+Date: 2019-07-01
+
+Log date: 2019-11-05
+
+## Status
+
+Accepted
+
+## Context
+
+We need to create Domain Models for all of the modules. Each Domain Model should represent a solution that solves a particular set of Domain problems (implements business logic).
+
+## Possible solutions
+1. Create Anemic Domain Model (Data Model) and implement *Transaction Script* pattern together with *Active Record* pattern
+2. Put all business logic to database in stored procedures
+3. Create a Rich Domain Model
+
+## Decision
+
+Solution number 3 - Rich Domain Model</br>
+
+1 - no, because the procedural style of coding will not be enough. We want to focus on behavior, not on the data.</br>
+2 - no, keeping business logic in the database is not a good idea in that case, object-oriented programming is better than T-SQL to model our domain and we don't have performance architectural drivers to resign from OOD.</br>
+
+We expect complex business logic with different rules, calculations and processing so we want to get as much as possible from Object-Oriented Design principles like abstraction, encapsulation, polymorphism. We want to mutate the state of our objects only through methods (abstraction) to encapsulate all logic and hide implementation details from the client (the Application Service Layer and Unit Tests).</br>
+
+## Consequences
+- All objects should be encapsulated (private by default principle) 
+- Encapsulation of objects implies more work in infrastructure (mapping to private fields, collections is harder)
+- Encapsulation of objects decreases to some level testability of these objects (Object-Oriented Design vs Testable Design)
+- All public methods of domain objects create Domain Model API
+- Implementation details of business logic are hidden
+- Clients of Domain Model are easier to implement
+- Better object-oriented programming skills are required to implement Rich Domain Model
+- Is easier to protect business rules/invariants using Rich Domain Model

docs/architecture-decision-log/0012-use-domain-driven-design-tactical-patterns.md

@@ -0,0 +1,32 @@
+# 12. Use Domain-Driven Design tactical patterns
+
+Date: 2019-07-01
+
+Log date: 2019-11-05
+
+## Status
+
+Accepted
+
+## Context
+
+We decided to use the Clean Architecture ([ADR #10](0010-use-clean-architecture-for-writes.md)) and create Rich Domain Models ([ADR #11](0011-create-rich-domain-models.md)) for each module. We need to define or use some construction elements / building blocks to implement our architecture and business logic.
+
+## Decision
+
+We decided to use **Domain-Driven Design** tactical patterns. They focus on the Domain Model implementation. Especially we will use the following building blocks:
+
+- Command - public method on Aggregate (behavior)
+- Domain Event - the immutable class which represents important fact occurred on a special point of time (behavior)
+- Entity - class with identity (identity cannot change) with mutable attributes which represents concept from domain
+- Value Object - immutable class without an identity which represents concept from domain
+- Aggregate - cluster of domain objects (Entities, Value Objects) with one class entry point (Entity as Aggregate Root) which defines the boundary of transaction/consistency and protects business rules and invariants
+- Repository - collection-like abstraction to persist and load particular Aggregate
+- Domain Service - stateless service to execute some business logic which does not belong to any of Entity/Value Object
+
+## Consequences
+- We need to define entities and value objects
+- We need to define aggregates boundaries
+- We need to add repositories for each aggregate
+- We can invoke only public methods on Aggregate Roots, everything else should be hidden
+- Developers need to be familiar with DDD tactical patterns

docs/architecture-decision-log/0013-protect-business-invariants-using-exceptions.md

@@ -0,0 +1,49 @@
+# 13. Protect business invariants using exceptions
+
+Date: 2019-07-01
+
+Log date: 2019-11-05
+
+## Status
+
+Accepted
+
+## Context
+
+Aggregates should check business invariants. When the invariant is broken, we should stop processing and return an error immediately to the client.
+
+## Possible solutions
+
+### 1. Use exceptions
+#### Pros
+- we can stop processing immediately (fail-fast)
+-  popular approach in C# 
+-  we don't need to check the result of each method (if-else statements)
+-   we can catch all Business Exceptions in one place and translate them (for example in the API layer to some HTTP response code). 
+#### Cons
+- indirection 
+- little performance impact 
+- for special cases, we need to add a specific catch.
+### 2. Return Result object
+#### Pros 
+- no indirection
+- no performance impact
+- signature method is more descriptive. 
+### Cons 
+- we need to add checks result of each method (if-else statements)
+- approach is less-known in the C# world 
+- it needs a library or more coding to support Results
+
+## Decision
+
+Solution number 1 - Use exceptions. </br>
+
+Performance cost of throwing an exception is irrelevant, we don't want too many if/else statements in entities, more familiar with exceptions approach.
+
+## Consequences
+- We need to add special *BusinessException* class to separate business rules validation exceptions from other exceptions
+- We need to create different business exceptions for each business rule
+- We will have a small performance impact (throwing exceptions)
+- We will have generic mechanism which catches *BusinessException*
+- We will not have a lot of if/else statements in Entities/Value Objects to check method results
+- Some monitoring tools logs automatically each exception. If we want to use one of this tool we should be aware of this and figure it out proper solution

docs/architecture-decision-log/0014-event-driven-communication-between-modules.md

@@ -0,0 +1,61 @@
+# 14. Event-driven communication between modules
+
+Date: 2019-07-15
+
+Log date: 2019-11-09
+
+## Status
+
+Accepted
+
+## Context
+
+Each module should be autonomous. However, communication between them must take place. We have to decide what will be the preferred way of communication and integration between modules.
+
+## Possible solutions
+
+### 1. Direct method call (synchronous)
+
+Each Module will expose a set of methods (interface, module API) which can be called by other modules directly.
+
+#### Pros
+- easier implementation
+- no indirection
+- more natural in the monolith architecture
+- supports immediate consistency
+#### Cons
+- less autonomy
+- strong coupling between modules
+- direct method call is blocking
+- module has a dependency on another module
+
+### 2. Event-driven (asynchronous)
+
+Each module will publish a specific set of events. Other modules can subscribe to specific events. It is the implementation of _Publish/Subscribe_ pattern.
+
+#### Pros
+- more autonomy
+- coupling is only to middleware/broker of events
+- no blocking communication
+- stronger modules boundaries
+- module does not have a dependency on another module
+#### Cons
+- indirection
+- more complex solution
+- middleware/broker is needed
+- does not support immediate consistency
+
+## Decision
+
+Solution number 2 - Event-driven (asynchronous)</br>
+
+We want to achieve the maximum level of autonomy and loose coupling between modules. Moreover, we don't want dependencies between modules. We allow direct calls in the future, but this should be an exception, not a rule.
+
+## Consequences
+- We need to implement the Publish/Subscribe pattern
+- Solution will be more complex
+- Modules will have more autonomy
+- Modules will have coupling to broker/middleware
+- During modules integration, eventual consistency will occur (asynchronous communication)
+- Events become Published Language of our Bounded Contexts (modules)
+- Events structure should be stable as much as possible