Skip to content

Solution Structure

  • Do create a separated Visual Studio solution for every module.
  • Do name the solution as GridLab.ModuleName (for core ABP modules, it's Volo.Abp.ModuleName).
  • Do develop the module as layered, so it has several packages (projects) those are related to each other.
  • Every package has its own module definition file and explicitly declares the dependencies for the depended packages/modules.

Layers & Packages

The following diagram shows the packages of a well-layered module and dependencies of those packages between them:

The ultimate goal is to allow an application to use the module in a flexible manner. Example applications:

  • A) A monolithic application;
  • Adds references to the Web and the Application packages.
  • Adds a reference to one of the EF Core or the MongoDB packages based on the preference.
  • The result;
    • The application can show UI of the module.
    • It hosts the application and domain layers in the same process (that's why it needs to have a reference to a database integration package).
    • This application also serves the module's HTTP API (since it includes the HttpApi package through the Web package).
  • B) An application that just serves the module as a microservice;
  • Adds a reference to HttpApi and Application packages.
  • Adds a reference to one of the EF Core or the MongoDB packages based on the preference.
  • The result;
    • The application can not show UI of the module since it does not have a reference to the Web package.
    • It hosts the application and domain layers in the same process (that's why it needs to have a reference to a database integration package).
    • This application serves the module's HTTP API (as the main goal of the application).
  • C) An application that shows the module UI but does not host the application (just uses it as a remote service that is hosted by the application A or B);
  • Adds a reference to the Web and the HttpApi.Client packages.
  • Configures the remote endpoint for the HttpApi.Client package.
  • The result;
    • The application can show UI of the module.
    • It does not host the application and domain layers of the module in the same process. Instead, uses it as a remote service.
    • This application also serves the module's HTTP API (since it includes the HttpApi package through the Web package).
  • D) A client application (or microservice) that just uses the module as a remote service (that is hosted by the application A, B or C);
  • Adds a reference to the HttpApi.Client package.
  • Configures the remote endpoint for the HttpApi.Client package.
  • The result;
    • The application can use all the functionality of the module as a remote client.
    • The application is just a client and can not serve the HTTP API of the module.
    • The application is just a client and can not show the UI of the module.
  • E) A proxy application that hosts the HTTP API of the module but just forwards all requests to another application (that is hosted by the application A, B or C);
  • Adds a reference to the HttpApi and HttpApi.Client packages.
  • Configures the remote endpoint for the HttpApi.Client package.
  • The result;
    • The application can use all the functionality of the module as a remote client.
    • This application also serves the module's HTTP API, but actually works just like a proxy by redirecting all requests (for the module) to another remote server.

Next section describes the packages in more details.

Domain Layer

  • Do divide the domain layer into two projects:
  • Domain.Shared package, named as GridLab.ModuleName.Domain.Shared, that contains constants, enums and other types those can be safely shared with the all layers of the module. This package can also be shared to 3rd-party clients. It can not contain entities, repositories, domain services or any other business objects.
  • Domain package, named as GridLab.ModuleName.Domain, that contains entities, repository interfaces, domain service interfaces and their implementations and other domain objects.
    • Domain package depends on the Domain.Shared package.

Application Layer

  • Do divide the application layer into two projects:
  • Application.Contracts package, named as GridLab.ModuleName.Application.Contracts, that contains application service interfaces and related data transfer objects.
    • Application contract package depends on the Domain.Shared package.
  • Application package, named as GridLab.ModuleName.Application, that contains application service implementations.
    • Application package depends on the Domain and the Application.Contracts packages.

Infrastructure Layer

  • Do create a separated integration package for each ORM/database integration like Entity Framework Core and MongoDB.
  • Do, for instance, create a GridLab.ModuleName.EntityFrameworkCore package that abstracts the Entity Framework Core integration. ORM integration packages depend on the Domain package.
  • Do not depend on other layers from the ORM/database integration package.
  • Do create a separated integration package for each major library that is planned to be replaceable by another library without effecting the other packages.

HTTP Layer

  • Do create an HTTP API package, named as GridLab.ModuleName.HttpApi, to develop a REST style HTTP API for the module.
  • HTTP API package only depends on the Application.Contracts package. It does not depend on the Application package.
  • Do create a Controller for each application service (generally by implementing their interfaces). These controllers uses the application service interfaces to delegate the actions. It just configures routes, HTTP methods and other web related stuffs if needed.
  • Do create an HTTP API Client package, named as GridLab.ModuleName.HttpApi.Client, to provide client services for the HTTP API package. Those client services implement application interfaces as clients to a remote endpoint.
  • HTTP API Client package only depends on the Application.Contracts package.
  • Do use dynamic HTTP C# client proxy feature of the ABP framework.

Web Layer

  • Do create a Web package, named as GridLab.ModuleName.Web, that contains pages, views, scripts, styles, images and other UI components.
  • Web package only depends on the HttpApi package.

Dependencies of the Projects in the Solution

The diagram below shows the essential dependencies (project references) between the projects in the solution

The projects have been explained before. Now, we can explain the reasons of the dependencies;

  • Domain.Shared is the project that all other projects directly or indirectly depend on. So, all the types in this project are available to all projects.
  • Domain only depends on the Domain.Shared because it is already a (shared) part of the domain. For example, an ModelType enum in the Domain.Shared can be used by an Model entity in the Domain project.
  • Application.Contracts depends on the Domain.Shared. In this way, you can reuse these types in the DTOs. For example, the same ModelType enum in the Domain.Shared can be used by a CreateModelDto as a property.
  • Application depends on the Application.Contracts since it implements the Application Service interfaces and uses the DTOs inside it. It also depends on the Domain since the Application Services are implemented using the Domain Objects defined inside it.
  • EntityFrameworkCore depends on the Domain since it maps the Domain Objects (entities and value types) to database tables (as it is an ORM) and implements the repository interfaces defined in the Domain.
  • HttpApi depends on the Application.Contacts since the Controllers inside it inject and use the Application Service interfaces as explained before.
  • HttpApi.Client depends on the Application.Contacts since it can consume the Application Services as explained before.
  • Web depends on the HttpApi since it serves the HTTP APIs defined inside it. Also, in this way, it indirectly depends on the Application.Contacts project to consume the Application Services in the Pages/Components.

Dashed Dependencies

When you investigate the solution, you will see two more dependencies shown with the dashed lines in the figure above. Web project depends on the Application and EntityFrameworkCore projects which theoretically should not be like that but actually it is.

This is because the Web is the final project that runs and hosts the application and the application needs the implementations of the Application Services and the Repositories while running.

This design decision potentially allows you to use Entities and EF Core objects in the Presentation Layer which should be strictly avoided. However, we find the alternative designs over complicated. Here, two of the alternatives if you want to remove this dependency;

  • Convert Web project to a razor class library and create a new project, like Web.Host, that depends on the Web, Application and EntityFrameworkCore projects and hosts the application. You don't write any UI code here, but use only for hosting.
  • Remove Application and EntityFrameworkCore dependencies from the Web project and load their assemblies on application initialization.