Repository files navigation

Food Delivery Microservices is a fictional food delivery microservices, built with .Net Core and different software architecture and technologies likeMicroservices Architecture,Vertical Slice Architecture ,CQRS Pattern,Domain Driven Design (DDD),Event Driven Architecture. For communication between independent services, we use asynchronous messaging with using rabbitmq on top ofMassTransit library, and sometimes we use synchronous communication for real-time communications with using REST and gRPC calls.

💡 This application is not business oriented and my focus is mostly on technical part, I just want to implement a sample with using different technologies, software architecture design, principles and all the thing we need for creating a microservices app.

WarningThis project is in progress. I add new features over the time. You can check theRelease Notes.

🎯 This Application ported tomodular monolith approach infood-delivery-modular-monolith repository, we can choose best fit architecture for our projects based on production needs.

Other versions of this project are available in these repositories, We can choose best fit architecture for our projects based on production needs:

• https://github.com/mehdihadeli/food-delivery-modular-monolith
• https://github.com/mehdihadeli/go-food-delivery-microservices

For your simplest .net core projects, you can use myvertical-slice-api-template project template:

• https://github.com/mehdihadeli/vertical-slice-api-template

If you like feel free to ⭐ this repository, It helps out :)

Thanks a bunch for supporting me!

• Features
• Plan
• Setup
  • Dev Certificate
  • Conventional Commit
  • Formatting
  • Analizers
• Technologies - Libraries
• The Domain and Bounded Context - Service Boundary
• Application Architecture
• Application Structure
• Vertical Slice Flow
• Prerequisites
• How to Run
  • Using PM2
  • Using Docker-Compose
  • Using Tye
  • Using Kubernetes
• Contribution
• Project References
• License

• ✅ UsingMicroservices andVertical Slice Architecture as a high level architecture
• ✅ UsingEvent Driven Architecture on top of RabbitMQ Message Broker and MassTransit library
• ✅ UsingDomain Driven Designin most of services like Customers, Catalogs, ...
• ✅ UsingEvent Sourcing andEventStoreDB inAudit Based services like Orders, Payment
• ✅ UsingData Centeric Architecture based onCRUD in Identity Service
• ✅ UsingCQRS Pattern on top ofMediatR library and splitingread models andwrite models
• ✅ UingStructured logging with serilog and exporting logs toElastic Seacrch andKibana throughserilog-sinks-elasticsearch sink
• ✅ UsingOutbox Pattern for all microservices forGuaranteed Delivery orAt-least-once Delivery
• ✅ UsingInbox Pattern for handlingIdempotency in reciver side andExactly-once Delivery
• ✅ UsingUnitTests andNSubstitute for mocking dependencies
• ✅ UsingIntegration Tests andEnd To End Tests on top oftestcontainers-dotnet library for cleanup our test enviroment through docker containers
• ✅ UsingMinimal APIs for handling requests
• ✅ UsingFluent Validation and aValidation Pipeline Behaviour on top of MediatR
• ✅ UsingPostgres for write database as relational DB andMongoDB andElasric Search for read database
• ✅ Using docker anddocker-compose for deployment
• ✅ UsingMicrosoft Tye for deployment
• ✅ UsingYARP reverse proxy as API Gateway
• ✅ Using different type of tests likeUnit Tests,Integration Tests,End-To-End Tests andtestcontainers for testing in isolation
• 🚧 UsingHelm,Kubernetes andKustomize for deployment
• 🚧 UsingOpenTelemetry for collectingMetrics andDistributed Traces

This project is in progress, new features will be added over time.

• ✔️.NET 8 - .NET Framework and .NET Core, including ASP.NET and ASP.NET Core
• ✔️MassTransit - Distributed Application Framework for .NET
• ✔️StackExchange.Redis - General purpose redis client
• ✔️Npgsql Entity Framework Core Provider - Npgsql has an Entity Framework (EF) Core provider. It behaves like other EF Core providers (e.g. SQL Server), so the general EF Core docs apply here as well
• ✔️EventStore-Client-Dotnet - Dotnet Client SDK for the Event Store gRPC Client API written in C#
• ✔️FluentValidation - Popular .NET validation library for building strongly-typed validation rules
• ✔️Swagger & Swagger UI - Swagger tools for documenting API's built on ASP.NET Core
• ✔️Serilog - Simple .NET logging with fully-structured events
• ✔️Polly - Polly is a .NET resilience and transient-fault-handling library that allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback in a fluent and thread-safe manner
• ✔️Scrutor - Assembly scanning and decoration extensions for Microsoft.Extensions.DependencyInjection
• ✔️Opentelemetry-dotnet - The OpenTelemetry .NET Client
• ✔️DuendeSoftware IdentityServer - The most flexible and standards-compliant OpenID Connect and OAuth 2.x framework for ASP.NET Core
• ✔️Newtonsoft.Json - Json.NET is a popular high-performance JSON framework for .NET
• ✔️Rabbitmq-dotnet-client - RabbitMQ .NET client for .NET Standard 2.0+ and .NET 4.6.1+
• ✔️AspNetCore.Diagnostics.HealthChecks - Enterprise HealthChecks for ASP.NET Core Diagnostics Package
• ✔️Microsoft.AspNetCore.Authentication.JwtBearer - Handling Jwt Authentication and authorization in .Net Core
• ✔️NSubstitute - A friendly substitute for .NET mocking libraries.
• ✔️StyleCopAnalyzers - An implementation of StyleCop rules using the .NET Compiler Platform
• ✔️Mapperly - A .NET source generator for generating object mappings, No runtime reflection.
• ✔️IdGen - Twitter Snowflake-alike ID generator for .Net

This application usesHttps for hosting apis, to setup a valid certificate on your machine, you can create aSelf-Signed Certificate, see more about enforce certificatehere andhere.

• Setup on windows andpowershell:

dotnet dev-certs https--cleandotnet dev-certs https-ep$env:USERPROFILE\.aspnet\https\aspnetapp.pfx-p<CREDENTIAL_PLACEHOLDER>dotnet dev-certs https--trust

• Setup inlinux and wsl:

dotnet dev-certs https --cleandotnet dev-certs https -ep${HOME}/.aspnet/https/aspnetapp.pfx -p<CREDENTIAL_PLACEHOLDER>dotnet dev-certs https --trust

dotnet dev-certs https --trust is only supported on macOS and Windows. You need to trust certs on Linux in the way that is supported by your distribution. It is likely that you need to trust the certificate in your browser(with this certificate we don't get an exception for https port because of not found certificate but browser shows us this certificate is not trusted).

In this app I useConventional Commit and for enforcing its rule I useconventional-changelog/commitlint andtypicode/husky with a pre-commit hook. For read more about its setup seecommitlint docs andthis article andthis article.

Here I configured a husky hook for conventional commits:

1. Install NPM:

npm init

2. Install Husky:

npm install husky --save-dev

3. Addprepare andinstall-dev-cert-bash commands for installing and activatinghusky hooks anddotnet tools in the package.json file:

• Actuallyprepare is a speciallife cycle scripts that runs automatically onlocal npm install without any arguments.
• Thescripts property of your package.json file supports a number of built-in scripts and their preset life cycle events as well as arbitrary scripts. These all can be executed by runningnpm run-script <stage> ornpm run <stage> for short.
• For workingdotnet tools restore commands to install and update local packages we should have a validnuget.config file in the root of our project. we can create anuget.config file with usingdotnet new nugetconfig command.

npm pkgset scripts.prepare="husky && dotnet tool restore"npm pkgset scripts.install-dev-cert-bash="curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v vs2019 -l ~/vsdbg"

{"scripts": {"prepare":"husky && dotnet tool restore","install-dev-cert-bash":"curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v vs2019 -l ~/vsdbg"  }}

4. Install CommitLint:

npm install --save-dev @commitlint/config-conventional @commitlint/cli

5. Create thecommitlint.config.js file with this content:

module.exports={extends:'@commitlint/config-conventional']};

6. Create the Husky folder:

mkdir .husky

7. Link Husky and CommitLint:

npx husky add .husky/commit-msg'npx --no -- commitlint --edit ${1}'

8. Activate and installing all husky hooks with this command:

npm run prepare# this command should run in git-bash on the windows or bash in the linuxnpm run install-dev-cert-bash

For formatting, I use mix ofbelav/csharpier anddotnet format.

• You can integrate csharpier with yourprefered IDE.
• You can useyour IDE watcher on save for applyingdotnet format rules. For Rider it is like this:

FileType: C#Scope: Open FilesProgram: Write dotnetArguments: format$SolutionPath$ -verbosity diagnostic --include$FileRelativePath$Advanced (Options)Disabled all advanced option checkboxes.All other values were left default

Here I configured a husky hook for formatting:

1. Install NPM:

npm init

2. Install Husky:

npm install husky --save-dev

3. Install manifest file withdotnet new tool-manifest because it doesn't exist at first time and then install our required packages as dependency withdotnet tool install, that will add todotnet-tools.json file in a.config directory:

dotnet new tool-manifestdotnet tool install csharpier

4. Addprepare command for installing and activatinghusky hooks andrestoring ourdotnet tools in the previous step to thepackage.json file:

npm pkgset scripts.prepare="husky && dotnet tool restore"

5. Create the Husky folder:

mkdir .husky

6. Link Husky and formatting tools:

npx husky add .husky/pre-commit"dotnet format --verbosity diagnostic"npx husky add .husky/pre-commit"dotnet csharpier . && git add -A ."

7. Activate and installing all husky hooks with this command:

npm run prepare

For roslyn analizers I use serveral analyzers and config the in.editorconfig file:

• StyleCop/StyleCop
• JosefPihrt/Roslynator
• meziantou/Meziantou.Analyzer
• Microsoft.VisualStudio.Threading.Analyzers

TODO

The bellow architecture shows that there is one public API (API Gateway) which is accessible for the clients and this is done via HTTP request/response. The API gateway then routes the HTTP request to the corresponding microservice. The HTTP request is received by the microservice that hosts its own REST API. Each microservice is running within its ownAppDomain and has directly access to its own dependencies such as databases, files, local transaction, etc. All these dependencies are only accessible for that microservice and not to the outside world. In fact microservices are decoupled from each other and are autonomous. This also means that the microservice does not rely on other parts in the system and can run independently of other services.

Microservices are event based which means they can publish and/or subscribe to any events occurring in the setup. By using this approach for communicating between services, each microservice does not need to know about the other services or handle errors occurred in other microservices.

In this architecture we useCQRS Pattern for separating read and write model beside of otherCQRS Advantages. Here for now I don't useEvent Sourcing for simplicity but I will use it in future for syncing read and write side with sending streams and usingProjection Feature for some subscribers to syncing their data through sent streams and creating ourCustom Read Models in subscribers side.

Here I have a write model that uses a postgres database for handling betterConsistency andACID Transaction guaranty. beside o this write side I use a read side model that uses MongoDB for better performance of our read side without any joins with suing some nested document in our document also better scalability with some good scaling features of MongoDB.

For syncing our read side and write side we have 2 options with using Event Driven Architecture (without using events streams in event sourcing):

• If ourRead Sides are inSame Service, during saving data in write side I save aInternal Command record in myCommand Processor storage (like something we do in outbox pattern) and after commiting write side, ourcommand processor manager reads unsent commands and sends them to theirCommand Handlers in same corresponding service and this handlers could save their read models in our MongoDb database as a read side.

• If ourRead Sides are inAnother Services we publish an integration event (with saving this message in the outbox) after committing our write side and all of ourSubscribers could get this event and save it in their read models (MongoDB).

All of this is optional in the application and it is possible to only use what that the service needs. Eg. if the service does not want to Use DDD because of business is very simple and it is mostlyCRUD we can useData Centric Architecture or If our application is notTask based instead of CQRS and separating read side and write side again we can just use a simpleCRUD based application.

Here I usedOutbox forGuaranteed Delivery and can be used as a landing zone for integration events before they are published to the message broker .

Outbox pattern ensures that a message was sent (e.g. to a queue) successfully at least once. With this pattern, instead of directly publishing a message to the queue, we put it in the temporary storage (e.g. database table) for preventing missing any message and some retry mechanism in any failure (At-least-once Delivery). For example When we save data as part of one transaction in our service, we also save messages (Integration Events) that we later want to process in another microservices as part of the same transaction. The list of messages to be processed is called aStoreMessage withMessage Delivery TypeOutbox that are part of ourMessagePersistence service. This infrastructure also supportsInbox Message Delivery Type andInternal Message Delivery Type (Internal Processing).

Also we have a background serviceMessagePersistenceBackgroundService that periodically checks the ourStoreMessages in the database and try to send the messages to the broker with using ourMessagePersistenceService service. After it gets confirmation of publishing (e.g. ACK from the broker) it marks the message as processed toavoid resending.However, it is possible that we will not be able to mark the message as processed due to communication error, for examplebroker isunavailable. In this case ourMessagePersistenceBackgroundService try to resend the messages that not processed and it is actually At-Least-Once delivery. We can be sure that message will be sentonce, but can be sentmultiple times too! That’s why another name for this approach is Once-Or-More delivery. We should remember this and try to design receivers of our messages asIdempotents, which means:

In Messaging this concepts translates into a message that has the same effect whether it is received once or multiple times. This means that a message can safely be resent without causing any problems even if the receiver receives duplicates of the same message.

For handlingIdempotency andExactly-once Delivery in receiver side, we could useInbox Pattern.

This pattern is similar to Outbox Pattern. It’s used to handle incoming messages (e.g. from a queue) forunique processing ofa single message onlyonce (even with executing multiple time). Accordingly, we have a table in which we’re storing incoming messages. Contrary to outbox pattern, we first save the messages in the database, then we’re returning ACK to queue. If save succeeded, but we didn’t return ACK to queue, then delivery will be retried. That’s why we have at-least-once delivery again. After that, aninbox background process runs and will process the inbox messages that not processed yet. also we can prevent executing a message with specificMessgaeIdmultiple times. after executing our inbox message for example with calling our subscribed event handlers we send a ACK to the queue when they succeeded. (Inbox part of the system is in progress, I will cover this part soon as possible)

Also here I usedRabbitMQ as myMessage Broker for my async communication between the microservices with using eventually consistency mechanism, for now I usedMassTransit tools for doing broker communications. beside of this eventually consistency we have a synchronous call with usingREST (in future I will use gRpc) for our immediate consistency needs.

We use aApi Gateway and here I usedYARP that is microsoft reverse proxy (we could use envoy, traefik, Ocelot, ...), in front of our services, we could also have multiple Api Gateway for reachingBFF pattern. for example one Gateway for mobile apps, One Gateway for web apps and etc.With using api Gateway our internal microservices are transparent and user can not access them directly and all requests will serve through this Gateway.Also we could use gateway for load balancing, authentication and authorization, caching ,...

In this project I usedvertical slice architecture orRestructuring to a Vertical Slice Architecture also I usedfeature folder structure in this project.

• We treat each request as a distinct use case or slice, encapsulating and grouping all concerns from front-end to back.
• When We adding or changing a feature in an application in n-tire architecture, we are typically touching many different "layers" in an application. we are changing the user interface, adding fields to models, modifying validation, and so on. Instead of coupling across a layer, we couple vertically along a slice and each change affects only one slice.
• WeMinimize couplingbetween slices, andmaximize couplingin a slice.
• With this approach, each of our vertical slices can decide for itself how to best fulfill the request. New features only add code, we're not changing shared code and worrying about side effects. For implementing vertical slice architecture using cqrs pattern is a good match.

Also here I usedCQRS for decompose my features to very small parts that makes our application:

• maximize performance, scalability and simplicity.
• adding new feature to this mechanism is very easy without any breaking change in other part of our codes. New features only add code, we're not changing shared code and worrying about side effects.
• easy to maintain and any changes only affect on one command or query (or a slice) and avoid any breaking changes on other parts
• it gives us better separation of concerns and cross cutting concern (with help of MediatR behavior pipelines) in our code instead of a big service class for doing a lot of things.

With usingCQRS, our code will be more aligned withSOLID principles, especially with:

• Single Responsibility rule - because logic responsible for a given operation is enclosed in its own type.
• Open-Closed rule - because to add new operation you don’t need to edit any of the existing types, instead you need to add a new file with a new type representing that operation.

Here instead of someTechnical Splitting for example a folder or layer for ourservices,controllers anddata models which increase dependencies between our technical splitting and also jump between layers or folders, We cut each business functionality into some vertical slices, and inner each of these slices we haveTechnical Folders Structure specific to that feature (command, handlers, infrastructure, repository, controllers, data models, ...).

Usually, when we work on a given functionality we need some technical things for example:

• API endpoint (Controller)
• Request Input (Dto)
• Request Output (Dto)
• Some class to handle Request, For example Command and Command Handler or Query and Query Handler
• Data Model

Now we could all of these things beside each other and it decrease jumping and dependencies between some layers or folders.

Keeping such a split works great with CQRS. It segregates our operations and slices the application code vertically instead of horizontally. In Our CQRS pattern each command/query handler is a separate slice. This is where you can reduce coupling between layers. Each handler can be a separated code unit, even copy/pasted. Thanks to that, we can tune down the specific method to not follow general conventions (e.g. use custom SQL query or even different storage). In a traditional layered architecture, when we change the core generic mechanism in one layer, it can impact all methods.

TODO

TODO

1. This application usesHttps for hosting apis, to setup a valid certificate on your machine, you can create aSelf-Signed Certificate, see more about enforce certificatehere.
2. Install git -https://git-scm.com/downloads.
3. Install .NET Core 7.0 -https://dotnet.microsoft.com/download/dotnet/7.0.
4. Install Visual Studio, Rider or VSCode.
5. Install docker -https://docs.docker.com/docker-for-windows/install/.
6. Make sure that you have ~10GB disk space.
7. Clone Projecthttps://github.com/mehdihadeli/food-delivery-microservices-sample, make sure that's compiling
8. Run thedocker-compose.infrastructure.yaml file, for running prerequisites infrastructures withdocker-compose -f ./deployments/docker-compose/docker-compose.infrastructure.yaml up -d command.
9. Openfood-delivery-microservices.sln solution.

For Running this application we could run our microservices one by one in our Dev Environment, for me, it's Rider, Or we could run it with usingDocker-Compose or we could useKubernetes.

For testing apis I usedREST Client plugin of VSCode its related file scenarios are available in_httpclients folder. also after running api you have access toswagger open api for all microservices in/swagger route path.

In this application I use afake email sender with name ofethereal as a SMTP provider for sending email. after sending email by the application you can see the list of sent emails inethereal messages panel. My temp username and password is available inner the all ofappsettings file.

For ruining all microservices and control on their running mode we could usePM2 tools. for installingpm2 on our system globally we should use this command:

npm install pm2 -g

After installing pm2 on our machine, we could run all of our microservices with running bellow command in root of the application with usingpm2.yaml file.

pm2 start pm2.yaml

Some PM2 useful commands:

pm2 -hpm2 listpm2 logspm2 monitpm2 info pm2.yamlpm2 stop pm2.yamlpm2 restart pm2.yamlpm2 delete pm2.yaml

• First we should create adev-certificate for our docker-compose file with this commands, see more about enforce certificatehere:

dotnet dev-certs https--cleandotnet dev-certs https-ep${HOME}/.aspnet/https/aspnetapp.pfx-p$CREDENTIAL_PLACEHOLDER$dotnet dev-certs https--trust

This local certificate will mapped to our containers in docker-compose file with setting~/.aspnet/https:/https:ro volume mount

• Our docker-compose files are based on linux
• Run thedocker-compose.infrastructure.yaml file, for running prerequisites infrastructures withdocker-compose -f ./deployments/docker-compose/docker-compose.infrastructure.yaml up -d command.
• Run thedocker-compose.services.yaml withdocker-compose -f ./deployments/docker-compose/docker-compose.services.yaml for production mode that uses pushed docker images for services or for development mode you can usedocker-compose.services.dev.yaml override docker-compose file withdocker-compose -f ./deployments/docker-compose/docker-compose.services.yaml -f ${workspaceFolder}/deployments/docker-compose/docker-compose.services.dev.yaml up command for buildingdockerfiles instead of using images in docker registry. Also fordebugging purpose of docker-containers in vscode you can use./deployments/docker-compose/docker-compose.services.debug.yaml override docker-compose file with runningdocker-compose -f ./deployments/docker-compose/docker-compose.services.yaml -f ${workspaceFolder}/deployments/docker-compose/docker-compose.services.debug.yaml up -d, I defined sometasks for vscode for executing this command easier. For debugging in vscode we should uselaunch.json.
• Wait until all dockers got are downloaded and running.
• You should automatically get:
  • Postgres running
  • RabbitMQ running
  • MongoDB running
  • Microservies running and accessible

Some useful docker commands:

// start dockersdocker-compose-f .\docker-compose.yaml up// build without cachingdocker-compose-f .\docker-compose.yaml build--no-cache// to stop running dockersdocker-compose kill// toclean stopped dockersdocker-compose down-v// showing running dockersdocker ps// to show all dockers (also stopped)docker ps-a

We could run our microservices with new microsoft tools with name ofProject Tye.

Project Tye is an experimental developer tool that makes developing, testing, and deploying microservices and distributed applications easier.

For installingTye globally on our machine we should use this command:

dotnet tool install -g Microsoft.Tye --version"0.11.0-alpha.22111.1"

OR if you already have Tye installed and want to update:

dotnet tool update -g Microsoft.Tye

After installing tye, we could run our microservices with following command in the root of our project:

tye run

One of key feature from tye run is a dashboard to view the state of your application. Navigate tohttp://localhost:8000 to see the dashboard running.

Also We could run somedocker images with Tye and Tye makes the process of deploying your application toKubernetes very simple with minimal knowledge or configuration required.

For using kubernetes we can use multiple approach with different tools likeplain kubernetes,kustomize andhelm and here I will use show use of all of them.

Here I uses plain kubernetes command and resources for applying kubernetes manifest to the cluster. If you're a Docker/Compose user new to Kubernetes, you might have noticed that you can’tsubstitutes andreplace theenvironment variables in your kubernetes manifest files (exception issubstitutes andreplace environment variables inenv attribute, with usingenvironment dependent variable). we often have some personal.env files for projects that we use to store credentials and configurations.

Forsubstitutes andreplace environment variables in our kubernetesmanifest orresource files we can useenvsubst tools, and we can even pipe it into other commands like Kuberneteskubectl, read more inthis andthis articles.

So here we should first install this tools on our OS withthis guid.

Now for running manifest files, firstly we shouldload ourenvironment variables inner.env file in ourcurrent shell session by usingsource .env command (after closing our shell environments will destroy).

Make sure to useexport, otherwise our variables are considered shell variables and might not be accessible toenvsubst

Here is a example of.env file:

exportASPNETCORE_ENVIRONMENT=dockerexportREGISTRY=ghcr.io

After loadingenvironment variables to the ourshell session we can run manifests with usingenvsubst and pipe envsubst output tokubectl command as a input like this example:

# pipe a deployment "deploy.yml" into kubectl applyenvsubst< deploy.yml| kubectl apply -f -

Also it is also possible to write oursubstitution to anew file (envsubst < input.tmpl > output.text):

envsubst< deploy.yml> compiled_deploy.yaml

I've create ashell scriptkubectl, we can call thisscript just like we wouldkubectl. This script sources any.env file in the manifests directory , If we're running./kubectl apply or./kubectl delete withkubectl script, it callsenvsubst toswap out your environment variables, then it passes the code on to thereal kubectl.

#!/bin/bashENV_FILE=.envsource$ENV_FILEif [["$1"=="apply" ]]|| [["$1"=="delete" ]];then    envsubst<$3| kubectl$1$2 -else    kubectl"$@"fi

• For installingInfrastructure manifests for kubernetes cluster we run bellow command withkubectl script:

./kubectl apply -f ./deployments/k8s/kubernetes/infrastructure.yaml

The application is in development status. You are feel free to submit pull request or create the issue.

• https://github.com/oskardudycz/EventSourcing.NetCore
• https://github.com/dotnet-architecture/eShopOnContainers
• https://github.com/jbogard/ContosoUniversityDotNetCore-Pages
• https://github.com/kgrzybek/modular-monolith-with-ddd
• https://github.com/thangchung/clean-architecture-dotnet

The project is underMIT license.