architecture_guide

Table of Contents

Introduction

Introduction

The devonfw platform provides a solution to building applications which combine best-in-class frameworks and libraries as well as industry proven practices and code conventions. It massively speeds up development, reduces risks and helps you to deliver better results.

Overview Onion Design

This guide shows the overall proposed architecture in terms of separated layers making use the Onion architecture pattern. Each layers represents a logical group of components and functionality. In this guide you will learn the basics of the proposed architecture based in layers in order to develop software making use of the best practices.

Layer specification

It is important to understand the distinction between layers and tiers. Layers describe the logical groupings of the functionality and components in an application; whereas tiers describe the physical distribution of the functionality and components on separate servers, computers, networks, or remote locations. Although both layers and tiers use the same set of names (presentation, business, services, and data), remember that only tiers imply a physical separation. It is quite common to locate more than one layer on the same physical machine (the same tier). You can think of the term tier as referring to physical distribution patterns such as two-tier, three-tier, and n-tier.

— Layered Application Guidelines
MSDN Microsoft

The proposed architecture makes use of cooperating components called layers. To develop specific functionality each layer contains a set of components which is capable to develop such functionalities.

The next figure represents the different layers:

Figure 1. High level architecture representation

The layers are separated in physical tiers making use of interfaces. This pattern makes possible to be flexible in different kind of projects maximizing performance and deployment strategies (synchronous/asynchronous access, security, component deployment in different environments, microservices…). Another important point is to provide automated unit testing or test-driven development (TDD) facilities.

Application layer

The Application Layer encapsulates the different .Net projects and its resource dependencies and manages the user interaction depending on the project’s nature.

Figure 2. Net application stack

The provided application template implements an dotnet API application. Also integrates by default the Swagger client. This provides the possibility to share the contract with external applications (angular, mobile apps, external services…).

Business layer

The business layer implements the core functionality of the application and encapsulates the component’s logic. This layer provides the interface between the data transformation and the application exposition. This allow the data to be optimized and ready for different data consumers.

This layer may implement for each main entity the API controller, the entity related service and other classes to support the application logic.

In order to implement the service logic, the services class must follow the next specification:

    public class Service<TContext> : IService where TContext: DbContext

PE: devon4Net API template shows how to implement the TODOs service as follows:

    public class TodoService: Service<TodoContext>, ITodoService

Where Service is the base service class to be inherited and have full access for the Unit of work, TodoContext is the TODOs database context and ITodoService is the interface of the service, which exposes the public extended methods to be implemented.

Data layer

The data layer orchestrates the data obtained between the Domain Layer and the Business Layer. Also transforms the data to be used more efficiently between layers.

So, if a service needs the help of another service or repository, the implemented Dependency Injection is the solution to accomplish the task.

The main aim of this layer is to implement the repository for each entity. The repository’s interface is defined in the Domain layer.

In order to implement the repository logic, the repository class must follow the next specification:

    Repository<T> : IRepository<T> where T : class

PE: devon4Net API template shows how to implement the TODOs repository as follows:

    public class TodoRepository : Repository<Todos>, ITodoRepository

Where Repository is the the base repository class to be inherited and have full access for the basic CRUD operations, Todos is the entity defined in the database context. ITodoRepository is the interface of the repository, which exposes the public extended methods to be implemented.

Note	Please remember that <T> is the mapped class which reference the entity from the database context. This abstraction allows to write services implementation with different database contexts

Domain layer

The domain layer provides access to data directly exposed from other systems. The main source is used to be a data base system. The provided template makes use of Entity Framework solution from Microsoft in order to achieve this functionality.

To make a good use of this technology, Repository Pattern has been implemented with the help of Unit Of Work pattern. Also, the use of generic types are makes this solution to be the most flexible.

Regarding to data base source, each entity is mapped as a class. Repository pattern allows to use this mapped classes to access the data base via Entity framework:

 public class UnitOfWork<TContext> : IUnitOfWork<TContext> where TContext : DbContext

Note	Where <T> is the mapped class which reference the entity from the database.

The repository and unit of work patterns are create an abstraction layer between the data access layer and the business logic layer of an application.

Note	Domain Layer has no dependencies with other layers. It contains the Entities, datasources and the Repository Interfaces.

devon4Net architecture layer implementaion

The next picture shows how the devon4Net API template implements the architectured described in previous points:

devon4Net api templare architecture implementation

Figure 3. devon4Net architecture implementations

Cross-Cutting concerns

Cross-cutting provides the implementation functionality that spans layers. Each functionality is implemented through components able to work stand alone. This approach provides better reusability and maintainability.

A common component set of cross cutting components include different types of functionality regarding to authentication, authorization, security, caching, configuration, logging, and communication.

Communication between Layers: Interfaces

The main target of the use of interfaces is to loose coupling between layers and minimize dependencies.

Public interfaces allow to hide implementation details of the components within the layers making use of dependency inversion.

In order to make this possible, we make use of Dependency Injection Pattern (implementation of dependency inversion) given by default in .Net Core.

The provided Data Layer contains the abstract classes to inherit from. All new repository and service classes must inherit from them, also the must implement their own interfaces.

Figure 4. Architecture representation in deep

Templates

State of the art

The provided bundle contains the devon4Net API template based on .net core. The template allows to create a microservice solution with minimal configuration.

Also, the devon4Net framework can be added to third party templates such as the Amazon API template to use lambdas in serverless envirnments.

Included features:

Logging:
Text File
Sqlite database support
Serilog Seq Server support
Graylog integration ready through TCP/UDP/HTTP protocols
API Call params interception (simple and compose objects)
API error exception management
Swagger:
Swagger autogenerating client from comments and annotations on controller classes
Full swagger client customization (Version, Title, Description, Terms, License, Json end point definition)
Easy configuration with just one configuration node in your settings file
JWT:
Issuer, audience, token expiration customization by external file configuration
Token generation via certificate
MVC inherited classes to access JWT user properties
API method security access based on JWT Claims
CORS:
Simple CORS definition ready
Multiple CORS domain origin definition with specific headers and verbs
Headers:
Automatic header injection with middleware.
Supported header definitions: AccessControlExposeHeader, StrictTransportSecurityHeader, XFrameOptionsHeader, XssProtectionHeader, XContentTypeOptionsHeader, ContentSecurityPolicyHeader, PermittedCrossDomainPoliciesHeader, ReferrerPolicyHeader
Reporting server:
Partial implementation of reporting server based on My-FyiReporting (now runs on linux container)
Testing:
Integration test template with sqlite support
Unit test template
Moq, xunit frameworks integrated
Circuit breaker:
Integrated with HttpClient factory
Client Certificate customization
Number of retries customizables
LiteDb:
Support for LiteDB
Provided basic repository for CRUD operations
RabbitMq:
Use of EasyQNet library to perform CQRS main functions between different microservices
Send commands / Subscribe queues with one C# sentence
Events management: Handled received commands to subscribed messages
Automatic messaging backup when sent and handled (Internal database via LiteDB and database backup via Entity Framework)
MediatR:
Use of MediatR library to perform CQRS main functions in memory
Send commands / Subscribe queues with one C# sentence
Events management: Handled received commands to subscribed messages
Automatic messaging backup when sent and handled (Internal database via LiteDB and database backup via Entity Framework)
SmaxHcm:
Component to manage Microfocus SMAX for cloud infrastructure services management
CyberArk:
Manage safe credentials with CyberArk
AnsibleTower:
Ansible automates the cloud infrastructure. devon4net integrates with Ansible Tower via API consumption endpoints
gRPC+Protobuf:
Added Client + Server basic templates sample gRPC with Google’s Protobuf protocol using devon4net
Kafka:
Added Apache Kafka support for deliver/consume messages and create/delete topics as well

Software stack

Table 1. Technology Stack of devon4Net
Topic	Detail	Implementation
runtime	language & VM	.Net Core Version 3.0
persistence	OR-mapper	Entity Framework Core
service	REST services	Web API
service - integration to external systems - optional	SOAP services	WCF
logging	framework	Serilog
validation	framework	NewtonSoft Json, DataAnnotations
component management	dependency injection	Unity
security	Authentication & Authorization	JWT .Net Security - Token based, local Authentication Provider
unit tests	framework	xUnit
Circuit breaker	framework, allows retry pattern on http calls	Polly
CQRS	Memory events and queue events	MediatR - EasyNetQ - Kafka
Kafka	Kafka support for enterprise applications	Confluent.Kafka
Fluent Validation	Fluent validation for class instances	Fluent validation