Architecture

Gazel has a layer and feature system. In this system, layers and features form a matrix which we call an application. This system allows you to create any type of software architecture to suit different needs.

There are three concepts: Application, Layer and Feature;

An Application consists of layers and features. It is designed according to an architectural pattern. For example, Service Application consists of Service Layer, Business Logic Layer and Data Access Layer whereas Api Application consists of Rest Api Layer and Service Client Layer.

A Layer introduces a new framework, library or SDK for an application to have a base to be configured. For example, Data Access Layer introduces NHibernate, IoC Layer introduces Windsor and so on.

A Feature configures one or more layers to make a certain functionality available to your application. For example, the feature Audit Option configures both Service Layer and Data Access Layer, so that it can log service requests as well as it adds audit columns to entities.

Assume we have an application with two layers and two features, below diagram represents this application from layer perspective;

flowchart TD
    subgraph LP[Layer Perspective]
        direction LR
        subgraph AL[A Layer]
            direction LR
            AL_XF([X Feature Configuration])
        end
        subgraph BL[B Layer]
            direction LR
            BL_XF([X Feature Configuration])
            BL_YF([Y Feature Configuration])
        end
    end
    AL -. depends on .-> BL

This is an application with two layers A Layer and B Layer, where A Layer only has a configuration from X Feature, but B Layer has configurations from both X Feature and Y Feature.

Let's look at the same application from feature perspective;

flowchart TD
    subgraph FP[Feature Perspective]
        direction TB
        subgraph XF[X Feature]
            direction LR
            XF_AL([A Layer Configuration])
            XF_BL([B Layer Configuration])
        end
        subgraph YF[Y Feature]
            direction LR
            YF_BL([B Layer Configuration])
        end
    end

Here you can see that this is an application with two features; X Feature and Y Feature with their configurations to relevant layers.

The difference between a layer and a feature is that a layer continue to exist without a configuration from a feature. So it only contains configurations from features. On the other hand, features consist of configurations, without them there won't be any features.

Finally you can see above application from application perspective;

flowchart LR
    subgraph AP[Application Perspective]
        direction LR

        subgraph L[Layers]
            direction LR
            AL[A Layer]
            BL[B Layer]
        end

        subgraph F[Features]
            direction LR
            XF{{X Feature}}
            YF{{Y Feature}}
        end

        XF -. configures .-> AL & BL
        YF -. configures .-> BL
    end

Now that you have learned three basic concepts Application, Layer and Feature, it is time to move on to next section.

Applications

Here we list built-in applications of Gazel. Every application has IoC Layer and Application Layer by default.

  • IoC Layer: This layer introduces dependency injection to all applications and base to all other layers.
  • Application Layer: This layer manages IApplicationBuilder instance and handles OnStart and OnStop configurations.

Service Application

Service application is designed to serve business functionality as internal services. This application is currently the only one that provides a data access layer. Below diagram illustrates a service application architecture;

flowchart LR
    subgraph SA[Service Application]
        direction LR
        SL[Service Layer]
        BLL[Business Logic Layer]
        DAL[Data Access Layer]
    end
    DB[(Database)]
    SL -.-> BLL -.-> DAL -.-> DB

It consists of three layers;

  • Service Layer: This layer gets domain objects from IoC container and exposes your public methods as internal business services.
  • Business Logic Layer: This layer scans your module assemblies and registers them to IoC container.
  • Data Access Layer: This layer gest persistent classes from IoC container and maps them to a database. This way it enables your application to communicate with an RDBMS.

Features

  • Audit
  • Authentication
  • Authorization
  • Cache
  • Crypto
  • Decimal Point
  • Exception Handling
  • File System
  • Hashing
  • Localization
  • Logging
  • Message Queue
  • Remote Call
  • Secure Call
  • Transaction
  • Utc

Middleware Application

Middleware Application consists of business modules without a data access layer and exposes configured methods as RESTful endpoints. Below you can see an architectural diagram of this application.

flowchart LR
    subgraph MA[Middleware Application]
        direction LR
        RAL[Rest Api Layer]
        SLCL[Service Local Client Layer]
        BLL[Business Logic Layer]
    end
    AS[A System]
    BS[B System]
    RAL -.-> SLCL -.-> BLL -.-> AS & BS

It consists of two layers;

  • Rest Api Layer: This layer contains runtime-generated controller classes which converts and forwards incoming messages to business services.
  • Service Local Client Layer: This layer serves as an adapter between Rest Api and Business Logic.
  • Business Logic Layer: This layer scans your module assemblies and registers them to IoC container.

Just like a service application you can create business modules but this time without a Data Access Layer. This means that within this application, you are expected to consume and orchestrate services from other systems.

Features

  • Audit
  • Authentication
  • Authorization
  • Crypto
  • Decimal Point
  • Exception Handling
  • File System
  • Hashing
  • Localization
  • Logging
  • Secure Call
  • Utc

Api Application

Api Application acts as an api gateway and exposes configured internal services to be available publicly via RESTful endpoints. Below you can see architectural diagram of this application.

flowchart LR
    subgraph AA[Api Application]
        direction LR
        RAL[Rest Api Layer]
        SCL[Service Client Layer]
    end
    subgraph SA[Service Application]
        direction LR
        SL[Service Layer]
    end
    RAL -.-> SCL -.-> SL
  • Rest Api Layer: This layer contains runtime-generated service classes which converts and forwards incoming messages to service client layer.
  • Service Client Layer: This layer accepts incoming messages, converts them to internal HTTP calls and redirects them to business services in a Service Application.

Features

  • Authentication
  • Exception Handling
  • Http Header
  • File System
  • Hashing
  • Localization
  • Logging
  • Secure Call
  • Utc

Gateway Application

Gateway Application is designed to serve desktop or single-page web applications that consumes directly internal business services. Unlike Api Application, it does NOT transform HTTP messages between client and service application. It only restricts client application to use a certain subset of internal business services.

flowchart LR
    subgraph GA[Gateway Application]
        direction LR
        GL[Gateway Layer]
        SCL[Service Client Layer]
    end
    subgraph SA[Service Application]
        direction LR
        SL[Service Layer]
    end
    GL -.-> SCL -.-> SL
  • Gateway Layer: This layer contains a ASP.NET Core middleware that forwards requests directly to the backing service application url. It can also restrict a service from consumption.
  • Service Client Layer: This layer configures url of backing service application and passes it to gateway layer.

Features

  • Application Session
  • Authentication
  • Hashing
  • Http Header
  • Logging
  • Utc

Command Line Application

Command Line Application is designed to easily develop CLIs. Unlike other applications it is not a web application. It only consists of a Command Layer;

flowchart LR
    subgraph GA[Command Line Application]
        direction LR
        GL[Command Line Layer]
    end
  • Command Line Layer: This layer scans application assembly to find implementations of ICommand interface and register command routing so that a CLI command is forwarded to the Execute method of your command classes.

Features

  • Exception Handling
  • File System
  • Localization
  • Logging

Layers

Below is the list of available layers in Gazel. Every layer introduces zero or more configuration interfaces. These configuration interfaces mostly act as wrappers around a new framework or library so that a feature can be built on top of those technologies provided by layers.

Default Layers

IoC Layer and Application Layer are default in all applications, hence it it is better to put them before the rest.

IoC Layer

Gazel uses Castle.Windsor as its dependency injection framework. This layer introduces two configurations:

  • IComponentModelBuilderConfiguration: Provides IComponentModelBuilder instance. Implement this configuration to add windsor interceptors or to make a change in lifecycles of already registered components.
  • IIoCConfiguration: Provides IKernel instance. Implement this to register new components. IServiceCollection is available to be resolved so that you can add other ASP.NET Core features.

Every layer configuration has a IKernel parameter for features to be able to Resolve components. IIoCConfiguration is the only type of configuration where it is safe to register new components.

Application Layer

This layer serves as a base for every application and exposes three configurations:

  • IApplicationBuilderConfiguration: Provides IApplicationBuilder instance. Use this configuration when you need to add new features via Use methods.
  • IOnStartConfiguration: This configuration is called right after application building is done. It is a hook on ApplicationStarted lifetime event.
  • IOnStopConfiguration: This configuration is called during ApplicationStopping lifetime event.

Business Logic Layer

Business logic layer scans your module assemblies, registers your classes to IoC container and configures methods to be exposed as business services. Gazel uses Routine to define a coding style. It has two configuration interfaces;

  • ICodingStyleConfiguration: Provides ConventionBasedCodingStyle instance. Use this configuration to introduce new conventions for your the classes in module projects.
  • IInterceptionConfiguration: Provides ConventionBasedInterceptionConfiguration. Use this configuration to register new interceptors to your business services.

Command Line Layer

Command line layer scans your application assembly to look for implementations of ICommand interface. Gazel uses CommandLineParser to parse arguments into command and options. This layer introduces one configuration;

  • ICommandLineConfiguration: Provides ParserSettings instance. Use this configuration to change the way CommandLineParser behaves.

Data Access Layer

Gazel makes use of Generic Repository Pattern with two interfaces IRepository<T> and ILookup<T>. With their NHibernate implementations NHibernateRepository<T> and NHibernateLookup<T>, Gazel enables your module classes to perform CRUD operations. Fluent NHibernate is used to configure data access layer by conventions.

To create a new configuration in this layer, there are two configuration interfaces:

  • IMappingConfiguration: Helps you to have an access to AutoPersistenceModel instance so that you can create new ORM conventions, or override existing conventions.
  • INHibernateConfiguration: Helps you to have an access to FluentConfiguration instance so that you can configure other things than class mappings.

For more information see Fluent NHibernate Documentation

Gateway Layer

This layer is created specificaly to make Gateway Application possible. It does not introduce a new library or framework, instead it introduces a custom configuration to enable some changes in gateway behaviour;

  • IGatewayConfiguration: Provides ConventionBasedGatewayConfiguration instance. Use this to change header mappings and/or to allow/forbid some requests.

Rest Api Layer

Gazel uses ASP.NET Core MVC to render controllers out of your business services. It generates source code, compiles and registers it during initalization of your application. It provides one configuration;

  • IRestApiConfiguration: Provides RestApiTemplate instance. Use this to change action routes, naming conventions and type conversions in generated code.

Service Client Layer

Service client layer registers an IClientContext instance to IKernel so that you can use it to make calls to business services internally. This layer uses Routine to make client requests to a remote http endpoint. As an example, Api Application makes use of this layer to consume business services from a given base URL. It comes with one configuration;

  • IServiceClientConfiguration: Provides ConventionBasedServiceClientConfiguration and ConventionBasedInterceptionConfiguration instances. Use this to alter request/response headers and/or intercept business services from client.

Service Layer

Service layer works directly with Business Logic Layer so that your domain objects can be accessed through http endpoints. This layer uses Routine to expose objects as services. It introduces two configuration interfaces:

  • IServiceConfiguration: Helps you to configure request and response headers of your busines services.
  • IServiceClientConfiguration: Provides ConventionBasedServiceClientConfiguration and ConventionBasedInterceptionConfiguration instances. Use this to alter request/response headers and/or intercept remote service calls from client.

Service Local Client Layer

This layer registers an IClientContext instance that consumes Business Logic Layer locally, without an HTTP layer. This layer serves as an adapter between layers that require IClientContext and layers that provide ICodingStyle, such as Middleware Application and does not introduce an additional configuration interface.