This box will disappear when printing mkdocs-print-site-plugin

This page has combined all site pages into one. You can export to PDF using File > Print > Save as PDF.

See also export to PDF and export to standalone HTML.

Domain Analysis

Domain Problem Analysis

In this section we have interviewed the company's manager with the aim of improving our understanding of the analyzed domain.

1. How is the waste collection currently managed?

   At the moment, garbage trucks periodically collect waste from the collection points. We have a schedule that tells us which types of waste we should collect on a given day. Each garbage truck starts from the disposal point and empties the dumpsters in all the collection points in its mission area. A garbage truck only collects one type of waste per mission.

   We would like to optimise the waste collection process in order for citizens to always be able to dispose of their waste in the nearest collection point.

2. How many dumpsters are there in each collection point?

   Depending on the amount of people that live in the area where the collection point is located, there may be one or several dumpsters for each type of ordinary waste. For instance, a collection point may have two dumpsters for plastic, two for paper and one for each other type of waste.

3. Which types of dumpsters are there in each collection point?

   The waste types that are collected in every collection point are unsorted, organic, plastic/aluminium, paper and glass. We are also thinking about introducing further kinds of waste.

   Dumpsters may also have different physical traits depending on the type of waste that they collect. Indeed, there are two different sizes of dumpsters. The larger one is suitable for types of waste that do not need to be collected frequently. On the other hand, the smaller one is used for instance for organic waste.

   At the moment, the larger dumpsters can be opened using a foot lever while the smaller ones are opened with hands. However, we would like citizens to be able to open all of them using a smart card.

4. Which types of waste are you willing to collect? How?

   We would like to be able to collect ordinary waste directly at collection points. On the other hand, we would like to provide an "at home" collection on demand for extraordinary waste.

   Ordinary waste includes:

   • paper
   • plastic/aluminium
   • glass
   • unsorted waste
   • organic waste

   Extraordinary waste includes:

   • twigs
   • waste oil
   • iron
   • electronics
   • clothes
   • others

5. What are the main characteristics of the dumpsters?

   The features of a dumpster are:

   • size: volume of waste it can contain (measured in liters)
   • color: indicates the type of waste that it contains
   • opening: it can be either through a foot lever or by hands.

6. Which information do you want to store about a single dumpster?

   For each dumpster we would like to know:

   • its occupied volume
   • whether it is open or closed
   • whether it is working or not
   • whether it needs to be emptied

7. Which kind of garbage trucks do you have? How many waste types can a single truck collect?

   We only have one type of truck. During a mission, it can only collect a single type of waste.

   We are also planning on acquiring specific trucks for extraordinary waste to be able to fulfill clients' requests.

8. How many garbage trucks do you have?

   There are from 10 to 30 trucks parked in every disposal point. The precise amount depends on the number of collection points in the same province as the disposal point.

9. Which information do you want to store about a single garbage truck?

   We would like to store:

   • its total capacity
   • current occupied volume
   • the type of waste that is currently being collected
   • its real time position

10. Where do the garbage trucks bring the waste?

    The waste is brought to the disposal point of that province.

11. So, do garbage trucks collect waste from every collection point of a province?

    No, each garbage truck is assigned to a mission, and therefore to a mission area. A mission area is made up of a set of residential areas that are physically close to one another.

12. How are disposal points distributed in the territory?

    There is a disposal point in every province. Each disposal point gathers waste from the collection points of that province. A province is further divided into residential areas where a single collection point is located. The residential areas are sized in a suitable way so that each one can cover the same amount of people.

13. Which waste types does a single disposal point manage?

    Each disposal point manages every type of waste. Each type of waste is handled by a specific disposal chain inside the disposal point.

14. How do you want to manage extraordinary waste?

    At the moment, extraordinary waste is directly brought to disposal points by citizens.

    However, we would like to let citizens book an appointment to collect extraordinary waste at their home.

Impact Mapping

The following impact map was derived from the analysis of the business problem. It allows to underline the main aspects of the problem, starting from the goal of the project. The goal is pursued by each actor in the system and the diagram helps to identify which deliverables will have the greater impacts. In fact, it can be seen as a first draft of the requirements.

Ubiquitous Language

The tables below represent the ubiquitous language derived from domain analysis. Each table describes terms related to the same topic.

Waste

Term	Description	Associations
Waste	Unwanted matter of material of any type, that citizens want to get rid of.	Type of Waste, Citizen
Type of Waste	Classification of the material of the waste.	Waste
Ordinary Waste	Set of types of waste that are daily produced by citizens.	Waste, Type of Waste, Citizen
Extraordinary Waste	Set of types of waste that are difficult to collect. This may be due to their dimension or composition.	Waste, Type of Waste, Collect
Unsorted Waste	Ordinary waste that is not recyclable.	Waste, Ordinary Waste
Plastic/Aluminium	Ordinary waste composed by plastic or aluminium.	Waste, Ordinary Waste
Paper	Ordinary waste composed by paper.	Waste, Ordinary Waste
Organic	Ordinary waste that is compostable over time.	Waste, Ordinary Waste
Glass	Ordinary waste composed by glass.	Waste, Ordinary Waste
Twigs	Extraordinary waste composed by pruning of trees or other bushes.	Waste, Extraordinary Waste
Waste Oil	Extraordinary waste composed by exhausted oil.	Waste, Extraordinary Waste
Iron	Extraordinary waste composed by iron.	Waste, Extraordinary Waste
Electronics	Extraordinary waste composed by electronic components.	Waste, Extraordinary Waste
Clothes	Extraordinary waste composed by old clothes.	Waste, Extraordinary Waste
Other Extraordinary Waste	Every other type that was not described previously.	Waste, Extraordinary Waste

Dumpster

Term	Description	Associations
Dumpster	A container for waste.	Waste
Type of Dumpster	Configuration of dumpster features.	Dumpster, Dumpster Feature
Features	Set of characteristics that describe a dumpster.	Dumpster
Size	Feature that represents dumpster's physical measure. It could be large or small.	Dumpster, Dumpster Feature
Large Size	Type of dumpster that can be opened using a foot lever. It can store up to 1000 liters.	Dumpster, Dumpster Feature, Type of Dumpster
Small Size	Type of dumpster that can be opened by hand. It can store up to 250 liters.	Dumpster, Dumpster Feature, Type of Dumpster
Color	Feature of dumpsters that shows the type of waste they collect.	Dumpster, Dumpster Feature
Opening	It defines the way dumpsters are opened. This can be done either using a foot lever or by hands.	Dumpster, Dumpster Feature
Capacity	The maximum amount of waste (in liters) that a single dumpster can store.	Dumpster, Dumpster Feature
Availability	Feature that states that the dumpster is working and its occupied volume percentage is under 95% of its capacity.	Dumpster, Dumpster Feature
Occupied Volume	The amount of waste (in liters) that a single dumpster is currently storing.	Dumpster, Dumpster Feature

Truck

Term	Description	Associations
Garbage Truck	A truck specially designed to collect waste and transport it to the disposal point.	Collect, Waste, Disposal Point
Truck Driver	A company's employee that drives garbage trucks.	Garbage Trucks
Capacity	The total amount of waste (in liters) that a garbage truck can store.	Waste, Garbage Truck
Occupied Volume	The amount of waste (in liters) that a garbage truck is currently storing.	Waste, Garbage Truck
Position	The current position of a garbage truck.	Garbage Truck
Availability	Feature that states whether the truck is busy in a mission.	Garbage Truck, Mission

Collection

Term	Description	Associations
Waste Collection	The action of picking up waste.	Waste
"At Home" Collection	The service that the company is willing to offer to collect extraordinary waste at citizens' houses.	Extraordinary Waste, Citizen
Collection Point	The group of dumpsters in a residential area.	Dumpster, Residential Area
Province	A geopolitical area a country is divided into. Each province has its own disposal point.	Disposal Point
Residential Area	A partition of a province. Each residential area has its own collection point.	Province, Collection Point
Mission	The trip that a garbage truck performs stopping at multiple collection points and collecting a single ordinary type of waste. Each mission consists of several mission steps.	Garbage Truck, Ordinary Waste, Collection Point, Mission Step
Mission Generation	The creation of a mission optimized for the best route that collects a set of dumpsters.	Dumpster
Mission Step	A phase of a mission corresponding to the collection of a dumpster.	Mission, Dumpster
"At Home" Mission	The trip that a garbage truck performs stopping at multiple citizens' houses and collecting a single extraordinary type of waste.	Garbage Truck, Extraordinary Waste, Collection Point
Mission Area	The set of residential areas covered by a garbage truck's mission.	Residential Area, Garbage Truck, Mission
Disposal Point	A set of buildings with many disposal chains used for waste disposal. Garbage trucks start and finish their missions here.	Disposal Chain, Waste, Garbage Truck, Mission
Disposal Chain	A sequence of machinery that treat a specific type of waste.	Type of Waste

User

Term	Description	Associations
User	A person who uses the system. It can be a citizen or a manager	Citizen, Manager
Citizen	An inhabitant of a residential area.	Residential Area
Manager	A system administrator.
Smart Card	A plastic card with a built-in microprocessor. It will be used to open dumpsters.	Dumpster
Complaint	A message that notifies an issue. It may be sent by citizens, truck drivers and dumpsters themselves.	Citizen, Truck Driver, Dumpster
"At Home" Collection Request	The request sent by a citizen to book an "At Home" collection.	Extraordinary Waste, Citizen
Booking	An "At Home" collection request scheduled appointment.	Citizen, "At Home" Collection Request, "At Home" Collection
Account	The digital identity associated to a user	User
Authenticate	The action of verifying a user's identity. It occurs when a citizen uses his smart card to open a dumpster or when a user accesses to the dashboard.	User, Smart Card, Dumpster, Dashboard
Dashboard	A graphic interface used by a user.	User

Ended: Domain Analysis

Requirements

User Stories

The following user stories describe the requirements of the required system.

As a Manager...

... I want to observe the real-time position of garbage trucks and the type of waste they are carrying so that I can monitor active missions.

... I want to observe the list of complaints received from citizens and dumpsters so that I can fix possible issues.

... I want to observe the list of active missions so that I can check the real time status of waste collection.

... I want to manage collection points, adding, removing and moving dumpsters or their location so that I can handle changes in cities.

... I want to observe collection points and dumpsters' status so that I can check whether the system is working or not.

... I want to observe disposal points' position so that I can have a visual representation of their location.

... I want to observe the list of "at home" collection requests so that I can verify the usefulness of the service.

... I want to create a new smart card for specific citizens so that they can open dumpsters with it.

As a Citizen...

... I want to open dumpsters with my smart card so that I can dispose waste effortlessly and without touching the dumpster.

... I want to book an "at home" waste collection so that I don't have to go to the disposal point.

... I want to observe all collection points so that I can see the types of waste that I can dispose of, the percentage of occupied volume for every dumpster and whether they are available or not.

... I want to report issues so that I can help improve the service.

As a Truck Driver...

... I want to automatically receive missions so that I can know which disposal points and which type of waste to collect.

... I want to automatically receive "at home" missions so that I can know which extraordinary waste collection requests I have to satisfy.

... I want to report issues so that I can notify managers about possible problems.

Benefit Mapping

The following benefit map has derived from the above user stories. It maps impacts and purposes to the actor who will benefit the most from them.

Use Cases

The following use cases diagrams describe the behavior of the system.

Ordinary Waste Management

Ordinary waste management is divided into two parts:

• disposal
• collection

Ordinary Waste Disposal

Regarding ordinary waste disposal, the main actors are citizens and dumpsters.

Citizens can dispose of waste inside dumpsters only if they use their smart card to make the opening request. Once the citizen has made the deposit, the dumpster will update its occupied volume and perform the automatic closure, which will occur after a predetermined amount of time.

Ordinary Waste Collection

Regarding ordinary waste collection, the main actors are trucks and dumpsters. In this scenario, trucks and truck drivers play the same role.

During its mission, a garbage truck shares its current location with the system and updates the mission status. At each step of the mission, the truck will update its current occupied volume and the emptied dumpster will do the same.

A mission is generated because at least one dumpster has sent a full dumpster notification.

Extraordinary Waste Management

Regarding extraordinary waste collection, the main actors are citizens and trucks. In this scenario, trucks and truck drivers play the same role.

A mission for extraordinary waste collection begins when at least one booking has been made by citizens.

The system will take care of generating an adequate mission that allows to optimize the garbage truck capacity and satisfy as many collection requests as possible.

Dashboard

The dashboard can be used by managers to observe dumpsters, 'at home' collection requests, the real-time position of trucks, disposal points and complaints. Moreover, it can be used by citizens to observe dumpsters and their personal 'at home' collection requests.

Complaints Management

Citizens and truck drivers can submit complaints. Complaints can be also submitted by dumpsters when they detect a problem. On the other hand, managers can monitor complaints.

Requirement Breakdown Structure

The team focused on use cases and user stories to identify and formalize the requirements, building a Requirement Breakdown Structure.

The goal that unites all the requirements is the optimization of waste collection. At the second level, the goal generates requirements (*). Then, structure presents functions (*.*) that describe the higher-level functionalities of each requirement. Each function splits up into many features (*.*.*) that explain specific details.

Optimize Waste Collection

Dumpster Infrastructure

1. Open dumpsters with smart-cards

   1.1 Authenticate smart-cards

   1.2 Open and close dumpsters

2. Collect and share data

   2.1 Update occupied volume

   2.2 Store information about citizens' disposals

   2.3 Send "full-dumpster" notification

   2.4 Raise complaints

Citizen App

1. Check dumpsters' status

   1.1 Graphic user interface with dumpsters inside collection points

   1.2 Check dumpsters' availability

   1.3 Check dumpsters' occupied volume

2. Extraordinary waste collection booking

   2.1 Create request

   2.2 Check requests' status

3. Raise complaints

   3.1 Write a complaint

   3.2 Send a complaint

Mission Management

1. Plan ordinary waste collection missions

   1.1 Find "full dumpsters" in the neighborhood

   1.2 Compute best route

2. Plan extraordinary waste collection missions

   2.1 Observe extraordinary mission requests

   2.2 Compute best route

Admin Dashboard

1. Check collection points' status

   1.1 Check dumpsters' availability

   1.2 Check dumpsters' occupied volume

   1.3 Check dumpsters' type

   1.4 Check collected type of waste

2. Check trucks' real time status

   2.1 Check trucks' real time position

   2.2 Check trucks' occupied volume

3. Check missions

   3.1 Check active missions

4. Check complaints

   4.1 Show list of complaints

   4.2 Check complaint's details

5. Register new citizens

   5.1 Creation of a new smart-card

The following diagram shows a visual representation of the requirements.

Ended: Requirements

Design

Domain Design

Subdomain & Bounded Contexts

As the final part of the domain analysis, the team focused on the identification of subdomains and bounded contexts within it. The team identified bounded contexts starting from the user stories.

Disposal Subdomain

Core Subdomain

This core subdomain manages the logic of all the components that make it possible to dispose of waste.

Dumpster's Monitoring & Control Context

It allows to continuously monitor and store information about the dumpster's state. For instance, the availability, the occupied volume, the stored type of waste and other useful information. Moreover, it also allows to remotely invoke operations on dumpsters, such as opening and closing them.

Collection Point Management Context

It is responsible for updating information about collection point's state, such as the insertion of a new dumpster and other functionalities. Moreover, it allows to access all the information about the collection point's state and its position.

Disposal Point Context

It stores information about disposal points.

Collection Subdomain

Core Subdomain

This core subdomain manages the logic of all the components that allow the company to collect waste. It's also responsible for creating missions and assigning those to trucks.

Truck's Monitoring & Control Context

It allows to continuously monitor and store information about the truck's state. For instance, it provides the position, the occupied volume, the carried waste type, whether it is involved in a mission and other useful information.

Mission Context

It is responsible for the generation of missions. Moreover, it assigns missions to available trucks.

Booking Context

It provides operations to create "at home" collection requests, to update and visualize them.

Complaint Subdomain

Supporting Subdomain

This supporting subdomain provides the functionalities that make it possible to notify, handle and close complaints.

Complaint Context

It provides functionalities to notify issues, read and manage them.

User Subdomain

Generic Subdomain

This generic subdomain contains the logic that manages all the entities that need to use system's functionalities.

Smart Card Context

It is the context that allows to create smart cards and to authenticate them.

Authentication Context

It is responsible for citizens' and managers' authentication.

Context Mapping

The following context mapping diagram represents relationships among subdomains and bounded contexts. The identified relationships are:

• partnership, a common symmetric relationship between two bounded contexts;
• upstream-downstream, an asymmetric relationship between two bounded contexts, where the downstream context adapts to the upstream one.

Domain Models

Disposal Domain Model

Model Diagram

The following diagram shows the aggregates of the disposal subdomain.

The Collection Point Aggregate is very important as it contains information about the dumpsters' position. Indeed, the dumpster is strictly correlated to the collection point it is contained into.

Domain Events

The Dumpster Aggregate deals with the following events:

• Citizen Disposal Event: generated when a citizen disposes of some waste.
• Dumpster Volume Update Event: generated when the volume sensor detects a disposal or a collection.
• Dumpster Availability Update Event: generated when the dumpster becomes available or unavailable.
• Opening Event: generated when the dumpster is opened.
• Closure Event: generated when the dumpster is closed.
• Mission Request Event: generated when the dumpster's occupied volume exceeds its threshold.

Domain Factories

• Dumpster Static Factory: generates dumpsters defining their TypeOfDumpster.

Domain Invariants

• TIMEOUT = 30 seconds.
• OCCUPIED_VOLUME_THRESHOLD = 75%.
• occupiedVolume < capacity.
• Citizen Disposal Events are accepted iff isAvailable.
• Opening Events are accepted iff isAvailable.
• isAvailable = isWorking && occupiedVolumePercentage < 95%.
• TypesOfWaste are mapped to one and one only Color, and vice versa.

Truck Domain Model

Model Diagram

The following diagram shows the truck's aggregate. It is the only aggregate identified in the truck's monitoring and control context.

Domain Events

The Truck Aggregate deals with the following events:

• Mission Request Event: received when a dumpster's occupied volume exceeds its threshold.
• Position Update Event: generated when the GPS sensor detects a new position.
• Truck Volume Update Event: generated when the truck empties a dumpster.
• Truck Availability Update Event: generated when a truck starts or ends a mission.
• Mission Step Event: generated when the truck leaves a collection point.

Domain Invariants

• occupiedVolume < capacity.
• Mission Request Event are accepted iff !isInMission.

Mission Domain Model

Model Diagram

The following diagram shows the mission's aggregate. It is the only aggregate identified in the mission context.

Domain Events

The Mission Aggregate deals with the following events:

• Mission Step Event: received when a truck leaves a collection point.
• Mission Request Event: received when a dumpster's occupied volume exceeds its threshold.
• Ordinary Mission Event: generated daily by the Mission Manager Service or upon Mission Request Event by dumpster.
• Extraordinary Mission Event: generated daily by the Mission Manager Service.

Domain Invariants

• Empty dumpsters cannot be assigned to missions.
• Dumpsters can be assigned to a mission iff it is not already in another mission (which is not completed).
• Unavailable trucks cannot be assigned to missions.
• Mission steps cannot be modified once the mission is created.

Ended: Domain Models

Ended: Domain Design

Architectural Design

Architectural Map

This section reports a high level architecture of the final system. This representation has been obtained by a further analysis of the identified subdomains, which allowed us to identify all the components of the system and define the main communications among them. The following diagrams describe all the components in the system, focusing on each subdomain, where all the bounded contexts are converted into functionalities for each described service.

The following diagrams present:

• Microservices: services that provide Application Program Interfaces that can be accessed externally. They are meant to interact with each other and provide their functionalities to other components.
• Physical Asset: devices on physical entities that allow to monitor sensors' data and control actuators.
• Digital Twin: digital representation of physical entities. Components in the system are meant to fetch information directly from digital twins instead of physical devices.

Disposal Subdomain

This diagram describes the main interactions among functionalities inside the Disposal Subdomain.

The Dumpster Microservice is the abstraction that covers all the identified bounded contexts in this subdomain. In fact, the microservice presents peculiar functionalities for each bounded context such as Dumpster Control, Disposal Point Management and Collection Point Management.

The Dumpster Microservice communicates with the digital twin of each dumpster in order to propagate the information to the concerned physical assets.

Collection Subdomain

The diagram highlights the communications that take place among the three microservices identified within the Collection Subdomain: Mission Microservice, Booking Microservice and Truck Microservice.

The Mission Microservice relies on an underlying database that allows to store the history and exposes the functionalities to generate and manage missions. In particular, if the microservice wants to generate an extraordinary mission, it will display the list of pending requests in the system by communicating with the Booking Microservice.

The Booking Microservice relies on a database that allows to have memory of all the requests for extraordinary waste collection that have been made so far.

The Mission Microservice then needs to communicate with the Truck Microservice to find out which trucks are available to take charge of the new mission and also to assign the mission that will be carried out by the truck.

The Truck Microservice takes care of the interaction with the digital twin which will propagate the information also to the physical asset.

Complaint Subdomain

This subdomain is represented with a single microservice that allows to expose an interface to the database that deals with complaints storage.

The Complaint Microservice takes care of complaints management, exposing methods that implement operations such as creating, deleting, modifying and selecting the information contained in the storage.

User Subdomain

The User Subdomain is represented with a microservice that takes care of exhibiting two main functionalities: Account Management and Smart Card Management.

The Account Management functionality is used to manage and store the information of system users, both on manager side and customer side. The authentication is mandatory to all the users that want to make requests for extraordinary waste collection and for managers that want to observe the system's operation.

The Smart Card Management functionality is necessary to let system operators generate new cards. They will be given to citizens in order to use them to open dumpsters.

The User Subdomain will then interact with the database that will store this information.

Subdomains Interactions

The following final diagram shows the interaction among microservices inside the identified subdomains. Further details inside each subdomain have been removed for a cleaner representation.

Service Architecture

The team agreed on building each microservice with a Clean Architecture (from now on referred as CA). Since there are many interpretations of what a CA is and what consequences it should bring, we portrayed our personal view, trying to stick with the principal layers that the literature presents.

Entities Layer (Domain)

At the center of a microservice, the principal elements that shall remain untouched are domain entities and rules. These aspects should be completely unaware of what is happening outside and decoupled from the technologies and libraries used.

Use Cases Layer (Application)

This layer is the bridge between the domain and the outside world. It describes a series of possible interactions that can be used from outside, and it should be the only way to access the domain. Use cases should be independent one from the other. In most of the cases, use cases involve communications with a persistence layer: in order to avoid the insertion of external libraries in this layer, we decided to provide a behavior encapsulated into a manager. The managers inside this layer are interfaces completely unaware of the particular instance of persistence. They just provide the API to interact with the domain. In outer layers, a link to persistence is granted by proper implementations of manager's interface (for instance, a DatabaseManager inheriting all the manager's APIs and connecting to a database).

Adapters Layer (Presentation)

The adapters layer grants validity to the communication among outer and inner layers. For instance, it can contain modules that allow to serialize and deserialize elements, achieving interoperability.

Drivers Layer (Frameworks)

The outermost layer manages all the external frameworks and drivers (persistence on databases, digital twins communication, etc.).

Ended: Architectural Design

Ended: Design

Implementation

Thanks to the Domain Driven Design carried on during the initial phase of the project, the team was able to conduct the implementation of the system's components concurrently. Before starting with the development the workload was equally divided among the members so that everyone could focus on a specific part of the domain and fully explore it. In order to let the other members know how the own implementation was being made, Git flow was very helpful because, before merging the code to the main branch, every developer had to make a pull request and request for other members' approval.

The communication among microservices happens by means of REST APIs exposed by each of them. The dumpster-microservice, truck-microservice and mission-microservice allow the management of the corresponding digital twins through the Azure Platform exposing CRUD APIs. On the other hand, the booking-microservice and complaint-microservice, expose routes to execute CRUD operations on a MongoDB Cluster instance. Finally, a mocked version of the dashboard was implemented using the Vue framework and it is hosted on Github Pages. The dashboard allows visualizing the position of collection points and trucks on a map and their properties.

The main language used was Kotlin, although the booking-microservice was written in Javascript. For the microservices written in Kotlin, Spring was used to create the web services, Azure Digital Twins Core to interact with Azure Platform and manage the digital twins, and KMongo to connect and operate with MongoDB databases. For the Javascript microservice Node.js was used to provide an execution environment, Express to create a web service and Mongoose to connect and operate with MongoDB databases.

At this stage of the implementation, that is not yet over, each microservice has been implemented and tested on its own. Nevertheless, the integration among microservices has not yet been tested, but the team expects that this process will be straightforward thanks to the initial domain model analysis. Thus, the last part of the implementation will concern the integration of the microservices and the development of the shadowing among physical assets and digital twins.

DevOps Techniques

DevOps engineering is a software development methodology that aims at communication and collaboration among developers and information technologies' workers. This set of techniques respond to interdependencies between software development and relative IT operations, allowing a faster and more efficient organization of software products and services.

The following paragraphs describe which DevOps techniques have been used in the making of the system, focusing on the advantages that each procedure has brought.

DVCS Strategy

Workflow

A GitHub organization named SmartWasteCollection was associated to the entire project. In this way, every aspect of the project could be handled in a specific repository inside the organization. Moreover, under the perspective of developing a system based on microservices, this model could help the team to better identify the components of the project.

The team agreed on working with Git Flow workflow inside the implementation repositories, adapting it following the specific needs. Before merging code on the main/master branch, feature branches need to be approved by other team members using the pull-request GitHub's service. In the "lightweight" repositories, such as the documentation one, the team chose not to use this complex mechanism.

All the feature branches will follow a common structure based on the following template:

feature/<committer-initial-name-letter><committer-initial-surname-letter>-<feature-name>

The adopted policy for branching strategy inside the organization's repositories is:

• rebase on the feature branches to make them updated with develop and main changes.
• merge the pull requests for develop and main with the new features introduced by developers.

Conventional Commit

The team worked with the conventional-commit convention. This strategy provides an easy set of rules for creating an explicit commit history and allows to automatically define the number of versions released.

The team agreed on an extension of the standard convention, using the following set of commit types:

• feat!: identifies a breaking change feature, increasing the major version number.
• feat: identifies a feature, increasing the minor version number.
• fix: identifies a patch change, increasing the patch version number.
• chore: identifies a minor change that doesn't affect the overall system's behaviour.
• docs: identifies an update to the documentation.
• ci: identifies changes in the repository's workflow definition.
• deps: identifies the update of a library dependency

Versioning

Following the conventional commit standard, the version number is defined in the format vX.Y.Z where:

• X indicates the major version and is incremented when a braking change occurs
• Y indicates a minor version and is incremented every time a new feature is introduced in the system
• Z indicates a patch version where typically errors are fixed and those changes do not modify the system APIs.

The other commit types defined in addition to those of conventional commit standard do not change the version number and are only used to identify the extent of the change within the code inside the repository.

Commit Lint Check

To ensure that developers follow the conventional commit standard, commit linting techniques are used within the repositories. These techniques allow you to check the validity of the messages made to the various commits before they are actually traced, in order to have a clean and traceable remote repository. If the linter encounters a validation error, the commit won't be published and an error is returned to the developer which summarizes what problems are present within its commit message.

Validation occurs by checking that a commit type is specified at the beginning of the commit message and possibly a parenthesis, suitably open and closed, which contains a summary description of what is the feature on which changes are being made. The commit type must be followed by a colon before continuing with a brief description of the extent of the changes made.

It was possible to configure commit linting within an npm project thanks to the @commitlint/config-conventional plugin. This plugin allows to import the rules that must be respected within a commit message in order to follow the conventional-commit standard and extend them appropriately, if necessary. These rules can then be used thanks to the husky plugin, which allows you to define git hooks that will run a script that executes the commit linter before ending the actual submission of the commit.

Within a gradle project it is possible to use the plugin org.danilopianini.gradle-pre-commit-git-hooks which allows to check the commit messages correctness before their submission.

Continuous Integration

GitHub Actions

The team decided to use the GitHub Actions service. The team developed the following set of GitHub Actions for the project:

• conventionalcommit-semantic-releasing: performs automatic releases of the project following the conventional-commit convention for version numbers.
• puml-markdown: embeds PlantUML code into markdown files.
• copy-files-action: copies files with names that match a specific pattern into another repository.

Moreover, the team used a bunch of other actions to perform tasks. Some of these are:

• markdown-docs: to deploy this GitHub Pages report from markdown files.
• azure-login: to log in to Azure services and perform tests.
• codecov-action: to push coverage reports to CodeCov.
• login-action: to log in to the GitHub Packages Container Registry.

Each repository has two active workflows, one for the Continuous Integration (CI) and another one for the Continuous Delivery (CD). The first one automatically executes build and test while the second one creates a release using the conventionalcommit-semantic-releasing action and then uploads a Docker image to the GitHub Packages Container Registry. The CD workflow has been suitably configured to run only if the CI has completed successfully.

Code Quality Control

A control on the quality of the code takes place thanks to the use of Git Flow, which allows the verification of the features introduced by a developer by all the other team members before they are merged into the main/master branch. It is the task of the other developers to check that the proposed features are actually working and written in an understandable and clean way.

Moreover, in the pre-commit hooks a code linter was included:

• ktlint for Gradle projects;
• ESLint for npm projects.

Tests

The team used:

• kotest, for testing Gradle projects;
• mocha, for testing npm projects.

The team produced coverage reports with the following plugins:

• jacoco, for Gradle projects;
• istanbul.js, for npm projects.

All coverage reports are published to codecov.io/SmartWasteCollection.

Automatic Dependency Update

The team agreed on using renovate for automatic dependencies updates.

Continuous Delivery

Semantic Versioning and Releasing

Thanks to the use of conventionalcommit-semantic-releasing action it was possible to automate all the versioning and releasing work. In particular, the action automatically calculates if a new version release is needed based on the committed commits in the main/master branch. If there is a commit that triggers a new version release (major, minor or patch) then the action creates the new tag, adding the appropriate version number to the one previously released, and then will create the GitHub Release with the reference of the last commit pushed on main/master branch.

If it's needed to attach some assets into the release that is generated, then the action allows to define a folder called /assets and all of its contents will be included in the GitHub Release.

If not needed within the repository, the folder can be deleted with a continuous integration task once the execution of the action is finished, in this way the repository could stay clean.

Containerization

Every microservice is containerized using Docker. The containers that connect to Azure Platform include a configuration script that makes it possible to authenticate to the service. On the other hand, the ones that connect to a database need to be provided with a connection string through environment variables. In order to be able to run the containers, they need three environment variables that contain the secrets needed to perform the login into the Azure Digital Twin service.

The images are build through a Github Action workflow which also logins to the Github Packages service and publishes them exploiting login-action. In order to grant the correctness and quality of the published images, this workflow is executed only if the Build and Test workflow is successful.

Licenses

Every repository in the organization is endowed with the MIT license. Therefore, the developed software is free and open-source.

Conclusion

The team is satisfied with the way the Domain Driven Design approach has been carried on. During the first part of the project the team members gathered to conduct knowledge crunching sessions. These latter allowed the team to reach a uniform knowledge about the domain. This was fundamental for the further steps of the project. In fact, even though the team members worked on different components of the system, everyone was able to stay coherent and adhere to the project's goal.

Moreover, the definition of subdomains and bounded contexts allowed designing correct size microservices. Indeed, they have a well-defined goal and a coherent set of functionalities. Also, the classification of the subdomains as core, supporting or generic made it easier to assign priorities regarding the implementation of the components of the system.

Finally, the decision to adopt a clean architecture for the implementation of the microservices allowed building software that is more resilient. In fact, the business logic is not influenced by the specific technologies, so it will most likely not change in the future.

Despite the initial part of knowledge crunching, throughout the implementation the team has felt the need to introduce new terms. These have been added right away to the ubiquitous language in order to avoid further misunderstandings.

During the first part of the implementation stage the team decided how to conduct the project from a DevOps point of view. The definition of pipelines that included tests and general code quality assurance allowed to automatically check that only "correct" code is deployed to the development environment. This was the first time that the team tried to fully exploit GitHub Actions and, even thought the implementation process is not yet over, the members have already understood their potential.

In conclusion, the team is satisfied with the job done and with the knowledge acquired from the project and the course.