TUNISIAN REPUBLIC

MINISTRY OF HIGH EEDUCATION

AND SCIENTIFIC RESEARCH
Private Polytechnic School of Sousse

Business intelligence department

End-of-Studies Report
Presented as part of the requirements for the

Applied Bachelor’s Degree in information Technology

Magor: Business Intelligence

project name

Prepared by
Ibrahim Karoui
Made within ....

Academic supervisor : professionnel supervisor :

 DEDICATIONS

I dedicate this report to my family, who have always supported me in my studies

and been a constant source of encouragement and motivation. I am grateful for their
unconditional love and moral support, which have enabled me to achieve my dreams.

I would also like to thank my friends and colleagues, who have been a great source of
support and inspiration throughout my final project. Their encouragement and support
have been invaluable, and I am grateful for their friendship.

Finally, I would like to express my gratitude to my teachers and supervisors, who have
guided and supported me throughout my final project. Their advice and expertise were
essential to the success of this project.

Thank you all for your unwavering support.”

Ibrahim Karoui

i
 ACKNOWLEDGMENTS

We give God the Most High praise for granting us good health and commitment to
beginning and completing this dissertation.

I want to express my gratitude to everyone in the team.

The Department of Education at the Private Polytechnic School of Sousse.

In honor of Dr. .... and Mr. ...... for introducing me to and guiding me on this topic.
For the, I’am grateful. both their extraordinary supervision’s quality and wealth, for
their persistence, rigor, accessibility and the efforts put forth throughout my dissertation
preparation.

I hope the jury’s members will recognize my true sentiments here. I appreciate them
giving me this honor by taking the time to examine this work by reading it.

ii
 CONTENTS

General Introduction 1

1 Presentation of the project framework 3

1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Introduction of the host company . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Study of the existing system . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.1 Current process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.2 Limitations of the current process: . . . . . . . . . . . . . . . . . . 4
1.3.3 Proposed system . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3.4 Advantages of the proposed system . . . . . . . . . . . . . . . . . . 6
1.4 Problematic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5 Proposed solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.6 Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.6.1 Choice of Methodology . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.6.2 Presentation of SCRUM . . . . . . . . . . . . . . . . . . . . . . . . 8
1.6.3 The SCRUM roles . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.6.4 Sprint planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.7 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2 Architecture : the standard 11

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2 Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3 The Tri-Nature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.1 purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.2 Dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.3 Exposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4 The principle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.1 EVERYTHING IS CONNECTED . . . . . . . . . . . . . . . . . . 13
2.5 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.5.1 Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.5.2 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.5.3 Exposers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.6 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

iii
 CONTENTS

3 Requirements 27
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2 Requirements specification . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2.1 Functional requirements . . . . . . . . . . . . . . . . . . . . . . . . 27
3.3 Non-functional requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.4 Presentation of use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.4.1 Presentation of actors . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.5 Use case description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.5.1 Use case : log in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.5.2 Register citizen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.5.3 Register agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.5.4 Submit Electronic Request . . . . . . . . . . . . . . . . . . . . . . 34
3.5.5 ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Brahim Karoui iv
 LIST OF FIGURES

1.1 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.2 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.1 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.2 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.5 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.6 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.7 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.8 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.9 sans titre!! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3.1 Use case diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

v
 LIST OF TABLES

1.1 Comparative study between project management methodologies . . . . . . 7

3.1 Description of the ”log in” use case for citizen . . . . . . . . . . . . . . . . 31

3.2 Description of the ”log in” use case for citizen . . . . . . . . . . . . . . . . 32
3.3 Description of the ” regester agent” use case for citizen . . . . . . . . . . . 33
3.4 Description of the ” submit Electronic Request ” use case for citizen . . . 34
3.5 .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

vi
 GLOSSARY OF ACRONYMS

Word Abbreviation
JWT Json Web Token
API Application Programming Interface
JSON JavaScript Object Notation
MVC Model View Controller
UML Unified Modeling Language
ORM Object Relational Mapping
UI User Interface
UX User EXperience
US Use Case
DOM Document Object Model

vii
 GENERAL INTRODUCTION

General introduction

During our internship at Cydista, we worked on developing an innovative application

aimed at simplifying the administrative procedures of citizens with the municipality. This
project is part of an effort to modernize public services and aims to facilitate people’s ac-
cess to information and official documents.
In this introduction, we will present our topic in detail and clearly and precisely explain
the problem we are trying to solve. We will also describe the plan of our report, outlining
what each chapter will cover.

Our project aims to allow citizens to electronically submit their requests for municipal
services using a simple and user-friendly interface. We have developed a complete sys-
tem for managing these requests, including features such as electronic request submission,
real-time tracking of request status, online payment of service fees, generation of official
documents with unique QR codes, management of electronic documents, and secure shar-
ing of these documents.

We have also emphasized making our application accessible, by including features de-
signed for the elderly and those with visual or hearing impairments. Finally, we have
ensured the security and confidentiality of data by implementing appropriate protection
measures.

1
 General Introduction

In the second part of this introduction, we will present the detailed plan of our report,
covering each stage of our project from needs analysis to presenting results and future
improvement perspectives.

In this report, we will start by presenting the framework of our project in chapter 1.
This chapter will include a brief introduction of the project and the company we worked
with, followed by an overview of the existing system that we sought to improve. We
will also describe the development model we chose and present the planning schedule we
followed. Finally, we will conclude the chapter with an overview of the objectives we set
for our project.

In chapter 2, we will present a detailed specification of the functional and non-

functional requirements we identified for our project. This will include a description of
the needs analysis process we followed, as well as a breakdown of functional requirements
into global needs and sub-needs. We will also present the non-functional requirements
and provide a list of the use cases we developed.

In chapter 3, we will present the design and architecture of the system we developed
for our application. This will include a detailed description of the dynamic and static
models we created, including sequence, collaboration, state, activity, and class diagrams.
We will also describe the architecture of our application, including the software and hard-
ware components.

In chapter 4, we will present the implementation of our application, including the

technologies and tools we used, as well as the challenges we encountered during the devel-
opment process. We will also provide a demonstration of our application’s functionality
and user interface.

Finally, in chapter 5, we will present the results of our project and discuss the future
perspectives for improvement and development. We will also provide a conclusion summa-
rizing our achievements and contributions to the field of municipal service management.

Brahim Karoui 2
CHAPTER 1

PRESENTATION OF THE PROJECT FRAMEWORK

1.1 Introduction

This chapter provides an overview of the project framework, including the hosting com-
pany, the current process, the proposed solution, the development approach, and the
project timeline. The aim is to set the stage for the project and provide a foundation for
the rest of the report. By the end of this chapter, you will have a good understanding of
the project framework and its objectives.

1.2 Introduction of the host company

This work is presented as part of the final project to obtain Business Intelligence licence.
The application was developed over a period of 6 months at CYDISTA.
Cydista is a Tunisian IT services company founded in 2020 by Mr. Mabrouk Mahdhi. It
has 20 employees and specializes in DOTNET technologies.

3
Chapter 1 Presentation of the project framework

It continues to establish itself as a leading player in the world of software solutions

and IT development, in French-speaking Africa and Europe, and is gaining recognition in
this field.

1.3 Study of the existing system

1.3.1 Current process

Currently, citizens who need to legalize their documents have to physically go to the city
hall office. Once there, they have to fill out the necessary documents and pay the required
fees. The officer then checks the citizen’s identity, signs and stamps the document. The
officer also creates a summary of the transaction and archives it for future reference. The
citizen then takes the document and uses it as needed.
The current process at the Tunisian town hall involves a lot of manual work and pa-
perwork. Agents have to handle a large number of documents and forms, which they
have to process manually. This process involves a lot of back and forth between different
departments, and it can be time-consuming and prone to errors. For example, an agent
might have to handle a citizen’s application for a permit or license, which requires them
to collect and verify various documents and information. They might have to contact
other departments or agencies to get the necessary approvals and signatures, which can
take days or even weeks. Finally, they have to file the completed application and keep
track of its progress.

1.3.2 Limitations of the current process:

The current process has several limitations. Firstly, it requires the citizen to physically
go to the municipality, which can be time-consuming and uncomfortable. Secondly, the
paperwork involved can be complex and confusing, especially for citizens who are not
familiar with the process. Finally, the manual nature of the process means that errors
and delays can occur, which can be frustrating for citizens.
Time-consuming: The manual nature of the process makes it very time-consuming. Agents
have to spend a lot of time handling paperwork and contacting different departments to
get the necessary approvals and signatures.

Brahim Karoui 4
Chapter 1 Presentation of the project framework

Prone to errors: Because the process involves a lot of manual work, it is also prone to
errors. Agents might misplace or lose documents, or they might make mistakes when
processing the information.
Inefficient: The current process is inefficient and does not make use of modern technology
to automate and streamline tasks. This means that agents have to spend more time and
effort than necessary to complete tasks.
Difficult to track progress: Because the process is manual, it can be difficult to track the
progress of applications or requests. Agents might have to rely on memory or physical
documents to keep track of where each application is in the process.
Not citizen-friendly: The current process can be frustrating for citizens who have to navi-
gate a complex and time-consuming system to get the services they need. This can lead to
dissatisfaction with the town hall’s services and a negative perception of the government.

1.3.3 Proposed system

The proposed system is a digital system accessible to users both online and offline. Online
users can register on the system and submit a request for a municipal service electroni-
cally.
The system will notify the citizen when their document is ready, and they can then go
to the city hall to verify their identity. Once the agent verifies the citizen’s identity, the
system will generate a signed document with a QR code and send it to the citizen via
email or a mobile application.
Offline users who are not comfortable with technology can still go to the city hall and sub-
mit their physical document. The agent will scan their ID card to retrieve their profile and
history from the system. The agent can then use the system to generate a QR code for the
document, print the document with the QR code attached, and hand it over to the citizen.

Here’s a corrected version of your proposed system: The proposed system is

a digital platform accessible to users both online and offline. Online users can register
on the system and submit a service request electronically. The system will process the
request and automatically generate a unique code that will be attached to the document.
For online users, once the document is ready, they will be notified through the system.

Brahim Karoui 5
Chapter 1 Presentation of the project framework

They can then access and download the document electronically, either through email or
a mobile application.
For offline users who are not comfortable with technology, they can visit the town hall in
person to submit their physical document. The agent at the town hall will process the
document and generate a unique code using the system. The code will then be attached
to the document, which will be printed and handed over to the citizen.
In summary, both online and offline users can submit their service requests. Online users
will receive their documents electronically, while offline users will receive printed docu-
ments with attached codes.

1.3.4 Advantages of the proposed system

The proposed system offers several advantages over the current process. Firstly, it elimi-
nates the need for citizens to physically go to the town hall, reducing the time and effort
required to legalize their documents. Secondly, the digital nature of the system makes it
easier for citizens to understand and use. Finally, the automated nature of the system
reduces the risk of errors and delaysp.
Increased efficiency: Digitizing the process can help automate many of the repetitive
tasks, which can save a lot of time and effort for the agents. For example, if forms and
applications are digitized, the agents will no longer have to manually process and organize
paper documents. This can lead to faster turnaround times and increased productivity.

Better data management: Digitizing the process can help ensure better data manage-
ment practices. Digital data can be easily stored, organized, and analyzed, which can
help agents make better decisions based on data insights.

Improved collaboration: Digitizing the process can facilitate better collaboration be-
tween agents within the town hall. For example, if a digital platform is used, agents
can easily share information and communicate with each other, which can help improve
overall coordination and teamwork.

Enhanced customer experience: Digitizing the process can help improve the customer

Brahim Karoui 6
Chapter 1 Presentation of the project framework

experience. For example, if forms and applications are available online, customers can
easily access them and submit them digitally. This can lead to a more convenient and
streamlined experience for the customer, which can help increase satisfaction and reduce
complaints.

1.4 Problematic
..........

1.5 Proposed solution

............

1.6 Methodology

1.6.1 Choice of Methodology

In order to successfully carry out a project, avoiding any risk of delay, it is necessary to
establish a precise and well-structured strategy that will be guided through all stages.

Table 1.1: Comparative study between project management methodologies

Brahim Karoui 7
Chapter 1 Presentation of the project framework

Methods Advantages Disadvantages

Planning-oriented. Long cycles.
Predictive Model Simple and robust
Waterfall Lack of flexibility. Low reactivity.
and Easy to implement.
Easy to implement.
Predictive model Shorter cycles
V-Model More flexibility. Better reactivity. More complex. More difficult.
Planning-oriented.
More adaptive than predictive model Lack of hindsight at the beginning
Spiral
Short cycles. Requires more effort.
Heavy and widely extended.
RUP Well-defined roles. for large projects that generate a lot
of documentation.
Rapid movement. Easy error correction. Difficult implementation Depends on
Agile Clear visibility of development. Small the maturity and dedication of all
teams, focused on pair development. participants.

After this study, we have chosen the Agile method ”SCRUM” as our working method-
ology which is well suited to achieve this objective.

1.6.2 Presentation of SCRUM

The SCRUM method is a project management method for software development. It is

one of the most widely used agile methods in the world. It is characterized by breaking
the project down into a series of iterations called ”sprints”, each sprint can last from one
week to one month and allows for the production of a functional part of the product to
be developed.

1.6.3 The SCRUM roles

There are three roles defined in Scrum:

Brahim Karoui 8
Chapter 1 Presentation of the project framework

Figure 1.1: sans titre!!

Product Owner (PO): Mr. Mabrouk Mahdhi. He represents the clients of the ap-
plication and explains the users’ needs and what should be done. He also decides whether
to accept or reject the project.
Scrum Master (SM): Mr. Kais Ben Hadj Hassan. He is the one who helps me respect
the Scrum methodology and solve the various problems encountered.
Scrum Team: We are a team of 3 consisting of Nour Essid, Mohamed Riadh Sahnoun,
and Kais Ben Hadj Hassan who work on the same project.

Figure 1.2: sans titre!!

Brahim Karoui 9
Chapter 1 Presentation of the project framework

1.6.4 Sprint planning

For the realization of our project we chose to develop 4string as follows:

-Sprint0:
-Sprint1:
-Sprint2:
-Sprint3:

1.7 Conclusion
In in this chapter, we introduced the project framework in which we worked. We started
by presenting the host company, giving an overview of its activities and goals. We then
examined the existing process for submitting and processing municipal service requests,
highlighting the limitations and challenges faced by citizens. Next, we presented the main
problematic and our proposed solution. Finally, we presented the adapted methodology to
develop our application. In the following chapter , we will be presenting the architecture:
the standard.

Brahim Karoui 10
CHAPTER 2

ARCHITECTURE : THE STANDARD

2.1 Introduction
When designing a system, it is of utmost importance for the designer to support their
design with some theory. Theories play an important role in ensuring that the objectives,
models, and simulations of their design are coherent and scalable within a certain domain.
The Standard is a collection of decades of industry experience in engineering, written by
Mr. Hassan Habib, a software engineer at Microsoft with more than 21 years of experience
in developing mobile, web, and enterprise applications.
In this chapter, we will explain this architecture in detail based on Hassan Habib’s book.

11
Chapter 1 Architecture : the standard

2.2 Definition
The Standard holds hundreds of years of collective experience from numerous different
engineers. HASSAN HABIB had the chance to work with several types of engineers -
some were crazy scientists who focused on the smallest details of every routine. And
others were business engineers who cared more about the final results than the means
to achieve those results. In addition to others, he learned from them all: what makes a
simple engineering guide that can light the way for all other engineers to be inspired by
and, hopefully, follow.
The origin of this idea that he began to look for a theory that could explain the world
and help distinguish what is true from what is not. What is right and what is wrong. So
after years and years of research, he settled on a theory that allowed for everything to be
understood: the Tri-Nature.

2.3 The Tri-Nature

The Tri-Nature theory states that everything in this world is comprised of 3 main cate-
gories. Dependencies, purposes, and exposures. Each of these components plays a crucial
role in its system’s survival, evolution, and fulfillment.

2.3.1 purpose

Everything around us has a purpose. It was created and designed with a specific reason
in the mind of its creator. We design cars to take us from point A to point B. We design
cups for drinking, plates for eating, and shoes for walking. Everything has a core purpose
that governs its design and legitimatizes its existence.

2.3.2 Dependency

But every system must have a dependency in one form or another in order. For instance,
we as biological systems rely on food and water to survive. Cars rely on oil or electricity.

Brahim Karoui 12
Chapter 1 Architecture : the standard

Computer systems rely on power and electricity and so on. Regardless of its impact and
importance, every method must have a dependency of some kind, no matter how small
or big it may be..

2.3.3 Exposition

Every system must expose itself to allow other systems to integrate and consume its ca-
pabilities. But to become a dependency, it must reveal itself somehow for other systems
to rely on it. For instance, power outlets are an exposure layer for power sources to allow
other systems to plug in and consume their services. Gas stations are exposure layers for
underground oil tanks to store that oil.

2.4 The principle

2.4.1 EVERYTHING IS CONNECTED

In the larger scheme of things, all systems out there are connected. A simple example
of this is the food chain in nature. The sun is a dependency for the grass to grow;
grasshoppers are grass consumers while frogs feed on grasshoppers, snakes feed off of
frogs, and so on.
Every member of the food chain is a system with dependencies, purposes, and exposure.

Figure 2.1: sans titre!!

Since computer systems are nothing but a reflection of our reality, these systems
integrations represent a chain of infinite dependencies where each one of these systems

Brahim Karoui 13
Chapter 1 Architecture : the standard

relies on one or more systems to fulfill its purpose. A simple mobile application could rely
on a backend system to persist its data. But the backend system relies on a cloud-based
system to store the data. And the cloud-based system relies on a file system to perform
basic persistence operations and so on.
The Tri-Nature pattern of Things could also be perceived at the smallest scale of any
system and the largest scale. Every system out there is infinitely comprised of three
components, each of which has three components and so on. That’s what we call a fractal
pattern.
For instance, the smallest known component in the universe is the quarks within neutron
within an atom. These quarks are three components, two down quarks and one up quark.
But if you zoom out slightly, you would see that the larger system where these quarks
reside is also comprised of three components: electrons, protons, and neutrons.

Figure 2.2: sans titre!!

2.5 Architecture
It is now evident that we can follow a theory to design systems! We can now develop
every component in our software according to The Tri-Nature of Everything. The rules
and guidelines that govern designing software according to The Theory is called The
Standard. It refers to the universal standard in designing systems in every matter.
The Standard dictates at the low-level architecture that every system out there should be
comprised of brokers (dependencies) and services (purposes), and exposers (exposures).
For instance, when designing a simple RESTful API, we may need to integrate with a
database system, then validate incoming data based on specific business rules and expose
these capabilities to the outside world for the API consumers to integrate with it.

Brahim Karoui 14
Chapter 1 Architecture : the standard

According to The Standard, that system would look like this:

Figure 2.3: sans titre!!

The same pattern would repeat itself when digging deeper into any of these compo-
nents. For instance, a service is comprised of validation components, processing compo-
nents, and integration components. And then, if we zoom in a bit further, these same
validation components are comprised of three more refined components: structural, logi-
cal, and external. The pattern continues to go on and on to the lowest level of our design,
as shown here:
The same pattern also applies to larger systems if we zoom out of the one system realm

Figure 2.4: sans titre!!

Brahim Karoui 15
Chapter 1 Architecture : the standard

into distributed modern systems such as microservice architectures - the same pattern
should apply as follows:
In a distributed system, some services play the role of ambassadors to external or local

Figure 2.5: sans titre!!

resources, equivalent to a broker component at the service level. But then a purpose-
driven component must come into play to orchestrate business flows by combining one
or many primitive resource-consumption operations from these ambassador services. The
final part is the exposure layer, a thin gatekeeper layer that becomes the first point of
contact between the outside world and your microservice architecture.
The same pattern of tri-nature will continue to repeat itself across several systems, may
it be large across multiple organizations or small within one single service.

2.5.1 Brokers

Brokers act as intermediaries between a software application and external resources such
as libraries, APIs, or services. They provide a local interface for the application to inter-
act with these resources, without being tightly coupled to any specific implementation.
Brokers are designed to be replaceable as technology evolves over time, and they abstract
away any specific dependencies on external resources.
By using brokers, your application becomes more pluggable and can be adapted to use

Brahim Karoui 16
Chapter 1 Architecture : the standard

different technologies or resources as needed. For example, if you have an API that cur-
rently uses a SQL server, a broker can be used to remove the SQL dependency and make
it easier to integrate with a NoSQL technology in the future. Overall, brokers allow your
application to be more adaptable, scalable, and cost-effective over time.
Brokers are typically located at the end of an application because they act as the last
point of contact between the custom code and external resources. This applies to various
types of applications, including mobile, desktop, web, and APIs. Brokers act as interme-
diaries between the custom code and external resources, whether they are local storage
or independent systems residing behind API’s.

Figure 2.6: sans titre!!

A-Characteristics

There are a few simple rules that govern the implementation of any broker - for example:
Implements a Local Interface :Brokers have to satisfy a local contract. They must
implement a local interface to allow the decoupling between their implementation and the
services that consume them For instance, given that we have a local contract IStorage-
Broker that requires an implementation for any given CRUD operation for a local model
Student - the contract operation would be as follows: public partial interface IStorage-
Broker IQueryable¡Student¿ SelectAllStudents();
An implementation for a storage broker would be as follows:
public partial class StorageBroker public DbSet¡Student¿ Students get; set;
public IQueryable¡Student¿ SelectAllStudents() =¿ SelectAll¡Student¿();
No Flow Control :Brokers should not have any form of flow-control such as if-
statements, while-loops, or switch cases - that’s because flow-control code is considered to
be business logic, and it fits better the services layer where business logic should reside,
not the brokers.

Brahim Karoui 17
Chapter 1 Architecture : the standard

For instance, a broker method that retrieves a list of students from a database would look
something like this:
No exception Handling :Exception handling is a form of flow control. Brokers are not
supposed to handle any exceptions but rather let the exception propagate to the broker-
neighboring services, where these exceptions can be properly mapped and localized.
Own Their Configurations :Brokers are also required to handle their configurations -
they may have a dependency injection from a configuration object to retrieve and set up
the configurations for whichever external resource they are integrating.
For instance, connection strings in database communications are required to be retrieved
and passed into the database client to establish a successful connection, as follows:
public partial class StorageBroker : EFxceptionsContext, IStorageBroker

code

Natives from Primitives :Brokers may construct an external model object based on
primitive types passed by broker-neighboring services For instance, in an e-mail notifica-
tion broker, input parameters for a .Send(...) function require the basic input parameters
such as the subject, content, or address Here’s an example:

code

The primitive input parameters will ensure there are no strong dependencies between
the broker-neighboring services and the external models. Even in situations where the
broker is simply a point of integration between your application and an external RESTful
API, it’s very highly recommended that you build your native models to reflect the same
JSON object sent or returned from the API instead of relying on NuGet libraries, DLLs
or shared projects to achieve the same goal.
Naming Conventions : The contracts for the brokers shall remain as generic as possi-
ble to indicate the overall functionality of a broker; for instance, we say IStorageBroker

Brahim Karoui 18
Chapter 1 Architecture : the standard

instead of ISqlStorageBroker to indicate a particular technology or infrastructure.

With a single storage broker, it might be more convenient to maintain the same name
as the contract. But in the case of concrete implementations of brokers, it all depends
on how many brokers you have providing similar functionality. In our case, we have a
concrete implementation of IStorageBroker, so the name would be StorageBroker.
However, if your application supports multiple queues, storage, or e-mail service providers,
you might need to start specifying the overall target of the component; for instance, an
IQueueBroker would have multiple implementations such as NotificationQueueBroker and
OrdersQueueBroker.
But if the concrete implementations target the same model and business logic, then a
diversion to the technology might be more befitting. In this case, for instance, IStorage-
Broker, two different concrete implementations could be SqlStorageBroker and MongoS-
torageBroker. This case is typical in situations where the intention is to reduce production
infrastructure costs.

Language : Brokers speak the language of the technologies they support. For in-
stance, in a storage broker, we say SelectById to match the SQL Select statement, and
in a queue broker, we say Enqueue to match the language.
If a broker is supporting an API endpoint, then it shall follow the RESTFul semantics,
such as POST, GET or PUT. Here’s an example:

code

Organization: Brokers supporting multiple entities, such as Storage brokers, should

leverage partial classes to break down the responsibilities per entity.
For instance, if we have a storage broker that provides all CRUD operations for both
Student and Teacher models, then the organization of the files should be as follows:

• IStorageBroker.cs
o IStorageBroker.Students.cs

Brahim Karoui 19
Chapter 1 Architecture : the standard

o IStorageBroker.Teachers.cs
• StorageBroker.cs
o StorageBroker.Students.cs
o StorageBroker.Teachers.cs

The primary purpose of this particular organization, leveraging partial classes, is to

separate the concern for each entity to a finer level, which should make the maintainability
of the software much higher.
But broker file and folder naming conventions strictly focus on the plurality of the entities
they support and the singularity for the overall resource supported.
For instance, we say IStorageBroker.Students.cs. And we also say IEmailBroker or IQueue-
Broker.Notifications.cs - singular for the resource and plural entities.
The same concept applies to the folders or namespaces containing these brokers.
For instance we say :

code

B-Type of brokers

Entity Brokers : Entity brokers provide integration points with external resources that
the system needs to fulfill business requirements.
For instance, entity brokers integrate with storage, providing capabilities to store or re-
trieve records from a database.
Entity brokers are also like queue brokers, providing a point of integration to push mes-
sages to a queue for other services to consume and process to fulfill their business logic.
Broker-neighboring services can only call entity brokers because they require a level of
validation on the data they receive or provide before proceeding any further.

Support Brokers : Support brokers are general purpose brokers, they provide the
functionality to support services, but they have no characteristic that makes them differ-
ent from any other system.

Brahim Karoui 20
Chapter 1 Architecture : the standard

A good example of support brokers is the DateTimeBroker - a broker specifically made

to abstract away the business layer’s strong dependency on the system date time. Time
brokers don’t target any specific entity, and they are almost the same across many sys-
tems. Another example of support brokers is the LoggingBroker - they provide data to
logging and monitoring systems to enable the system’s engineers to visualize the overall
flow of data across the system and be notified in case any issues occur.
Support Brokers may be called across the entire business layer: on foundation, processing,
orchestration, coordination, management, or aggregation services, unlike Entity Brokers.
That’s because logging brokers are required as a supporting component in the system to
provide all the capabilities needed for services to log their errors or calculate a date or
any other supporting functionality.

2.5.2 Services

Services are the core component of any system that contains all the business logic. The
main goal of services is to be agnostic from specific technologies or external dependencies,
and they should be able to plug into any other dependencies and exposure technologies
with the least amount of integration effort.
Services mainly include validation, processing, and integration operations.
Validations ensure that incoming or outgoing data match a particular set of rules, process-
ing operations focus on the flow-control, mapping, and computation to satisfy a business
need, and integration operations focus on retrieving or pushing data from or to any inte-
grated system dependencies. The design of services is to be pluggable and configurable,
making it easy to integrate with any technology from a dependency standpoint and easy
to plug into any exposure functionality from an

Brahim Karoui 21
Chapter 1 Architecture : the standard

Figure 2.7: sans titre!!

A- Services Types

Services have several types based on their disposition in any given architecture. They fall
under three main categories: validators, orchestrators, and aggregators.

Figure 2.8: sans titre!!

Brahim Karoui 22
Chapter 1 Architecture : the standard

Validators Validator services are mainly broker-neighboring services or foundation

services.
These services’ primary responsibility is to add a validation layer on top of the existing
primitive operations, such as the CRUD operations, to ensure incoming and outgoing
data is validated structurally, logically, and externally before sending the data in or out
of the system.
Orchestrators Orchestrator services are the core of the business logic layer. They can be
processors, orchestrators, coordinators, or management services, depending on the type
of their dependencies.
Orchestrator services mainly focus on combining multiple primitive operations or multiple
high-order business logic operations to achieve an even higher goal.
Orchestrator services are the decision makers within any architecture, the owners of the
flow control in any system, and the main component that makes one application or soft-
ware different from the other.
We intentionally design Orchestrator services to be longer-lived than any other type of
service in the system.
Aggregators
Aggregator services’ primary responsibility is to tie the outcome of multiple process-
ing, orchestration, coordination, or management services to expose one single API for any
given API controller or UI component to interact with the rest of the system.
Aggregators are the gatekeepers of the business logic layer. They ensure the data expo-
sure components (like API controllers) are interacting with only one point of contact to
interact with the rest of the system.
Aggregators, in general, don’t care about the order in which they call the operations that
are attached to them. Still, it is sometimes necessary to execute a particular operation,
such as creating a student record before assigning a library card.
In the following chapters, we will discuss each type of these services.

2.5.3 Exposers

Exposers are disposable components in any system that has the single responsibility of
exposing your core business logic functionality by mapping its responses to a certain pro-

Brahim Karoui 23
Chapter 1 Architecture : the standard

tocol. For instance, in RESTful communications, an API controller would be responsible

for returning a 200 code for a successful response. The same thing applies to other proto-
cols such as gRPC or SOAP or any other protocol of communication between distributed
systems.
Exposer components are similar to Brokers. They are the last point of contact between
the core business logic and the outside world. They are built with the intent that they
will be detached from the current system at some point in time to allow the very same
core logic to integrate with modern systems, protocols or interfaces.

Figure 2.9: sans titre!!

A-Purpose

In general, exposure components main responsibility is to allow someone or something to

interact with your business logic. In that core purpose a precise mapping bit by bit to
every possible response from your core business logic should be communicated cautiously
with the consumer to that logic. I say cautiously because sometimes certain internal is-
sues in the system are not required to be exposed to the outside world. This mapping of
responses can usually be a zero effort as the protocol and the language your code business
logic communicate are the same such as the case with libraries produced to run on the
system that use the same technologies or programming languages.

Brahim Karoui 24
Chapter 1 Architecture : the standard

But there are occassions where the outside world stateless protocol doesn’t necessarily
match the same value of a response. In which case it becomes an exposer component
responsibility to make a successful mapping both ways in and out of the system. API
controllers are a great example of that. They will communicate a 4xx issue when there’s
a validation exception of some type and return a deserialized JSON value if the commu-
nication was successful. But there are also more details around problem details, error
codes and other levels of mapping and communication that we will discuss in upcoming
chapters within this section.

B-Pure Mapping

The most important aspect of exposure components is that they are not allowed to com-
municate with brokers of any type. And they are not allowed to contain any form of
business logic within them. By business logic here I mean no sequence of routine calls, no
iteration or selection/decision making. The same way it is with brokers, they only link
an existing realm with the outside realm to achieve a certain value.

C-Types of Exposure Components

Communication Protocols An exposure component that is a communication protocol

can vary from simple RESTful APIs, to SOAP communication or gRPC. They can also be
a simple client in a library where consumers would just install the library in their projects
and consume your core logic through the client APIs. These examples are all of the same
type of exposure components.
The differentiator here is that a communication protocol is usually event-based. Triggered
by an incoming communication and treated with a response of any kind. Communication
protocols are usually for system-to-system integrations but they can be accessible and
understandble by humans for testing and debugging purposes.
User Interfaces Another type of exposer components are user interfaces. This can vary
from Web, mobile or desktop applications including simple command lines. They mainly
target end-users for communication but can be automated by other systems. Especially
with command line user interfaces.In this day and age, user interfaces can also include

Brahim Karoui 25
Chapter 1 Architecture : the standard

virtual and augmented realities, metaverses and any other form of software
There are occasions where Human-Machine-Interfaces (HMI) can also fall into that level
of exposure components. For instance, the buttons on a cellphone, keyboards we use
everyday and any form of hardware that can interact directly with core business logic
interfaces as an exposure component. The same theory applies to the Internet of Things
(IoT) components and many others where a human has to utilize a component to leverage
a certain capability to their own advantage in anyway.
Components Some exposure components are not necessarily a system interfacing with
another system. Neither they are purposed to communicate with humans. They are
daemons or IO based components that do something in the background without a trig-
ger. usually these components are time-based and they may leverage existing protocols
or just simply interface directly with the core business logic which are both viable options.

2.6 Conclusion

Brahim Karoui 26
CHAPTER 3

REQUIREMENTS

3.1 Introduction
This chapter is a key step in the development of our project since the success of your
study depends on the quality of its specifications. It is therefore necessary to properly
identify and challenge all the needs users to take into account the project environment
and clarify the functionalities to be integrated into the project. The representation of
needs is expressed as case diagrams Which allow users to be clearly represented as well
as interactions between actors and the application. The pre-study is the very first step in
that process. It’s initial identification of functional and technical requirements.

3.2 Requirements specification

An analysis of the application’s objectives allowed us to identify the different requirements
that must be satisfied in our application. These requirements are classified into two
categories: functional requirements and non-functional requirements.

3.2.1 Functional requirements

A functional requirement is a requirement specifying an action that a system must be

able to perform Without considering any physical constraint. In our context the system
must allow the following tasks :

27
Chapter 3 Requirements

1. User registration and login:

Users should be able to create an account by providing their personal details and contact
information.
Users should be able to log in using their registered email and password.
2. Electronic request submission:
Users should be able to submit a request for a town hall service electronically.
Users should be able to select the type of service they need.
Users should be able to upload any necessary documents.
3. Notification system:
The system should provide real-time updates to users about the status of their requests.
The system should notify users when their document is ready for verification.
4. Online fee payment:
The system should allow users to pay fees associated with town hall services online.
The system should accept a variety of payment methods
5. Verification process:
The agent should be able to scan the user’s ID card to retrieve their profile and history
from the system.
The agent should be able to verify the user’s identity.
6. QR code generation:
The system should be able to generate a QR code for the document.
The QR code should be able to retrieve information about the document and its status.
7. Digital document management:
The system should allow users to store and manage digital copies of their documents.
8. Document sharing:
Users should be able to share their digital documents with other individuals or organiza-
tions.
Sharing should be possible through email or other digital means.
9. User profile management:
The system should allow users to view and edit their personal details and contact infor-
mation.
The system should allow users to view their service request history.
The system should allow users to track the status of their current requests.

Brahim Karoui 28
Chapter 3 Requirements

10. Accessibility features:

The system should include accessibility features such as larger font sizes and text-to-
speech functionality.
The features should make it easier for older citizens with visual or hearing impairments
to use the system.
11. User feedback: The system should allow users to provide feedback on their expe-
riences with the system.
The system should allow users to suggest improvements to the town hall’s services.
12. Archive management:
The system should automatically generate and manage a digital archive of all documents
processed by the town hall.
The archive should include details about the user, the type of request, and the date it
was processed.
13. Printing and document distribution:
The system should allow agents to generate a QR code for a physical document.
The document should have the QR code attached.
14. Security and privacy:
The system should incorporate appropriate security measures to protect user data.
The measures should include encryption, access controls, and regular security audits.
15. Agent-assisted service:
The system should provide an agent-assisted service for citizens who are not comfortable
with digital apps.
The service should allow citizens to receive assistance from an agent in submitting re-
quests and completing other tasks related to town hall services
16. Easy document submission:
The system should provide an easy and intuitive way for citizens to submit their physical
documents to the agent for processing.
The agent should be able to scan the citizen’s identity card to retrieve their profile and
history.
The agent should be able to generate a QR code that can be attached to the document.
17. Agent training and support:
The system should provide training and support to town hall agents.

Brahim Karoui 29
Chapter 3 Requirements

The training and support should ensure that agents are comfortable with the system and
can provide effective assistance to citizens.
18. Clear and concise instructions:
The system should provide clear and concise instructions to citizens on how to use the
system.The instructions should include step-by-step guides and video tutorials.
19.
The system should provide tools for administrators to manage user accounts, service re-
quests, and document processing.

3.3 Non-functional requirements

The operating requirements describe the properties of the application and characterize it.
These are needs in terms of security performance and accessibility. These requirements
which do not specifically concern the system but identify both its internal and external
constraints.
Performance: The system should be able to handle a high volume of requests and trans-
actions, with minimal lag time or delays.
Reliability: The system should be reliable and available 24/7, with a high level of uptime
and minimal downtime for maintenance or upgrades.
Security: The system should incorporate appropriate security measures to protect user
data and prevent unauthorized access, such as encryption, access controls, and regular
security audits.
Scalability: The system should be able to scale up or down as needed to accommodate
changes in demand or usage patterns, without affecting performance or functionality.
Compatibility: The system should be compatible with a wide range of devices, plat-
forms, and operating systems, to ensure maximum accessibility for all users. Usability:
The system should be easy to use and navigate, with clear and concise instructions and
minimal complexity. Maintainability: The system should be easy to maintain and
update, with clear documentation and an intuitive user interface for administrators and
developers.
Availability: The system should be available to users at all times, with minimal down-

Brahim Karoui 30
Chapter 3 Requirements

time or service interruptions.

Accessibility: The system should be accessible to users with disabilities, with appropri-
ate features and accommodations to ensure maximum usability and functionality.
Data management: The system should be able to manage and store large amounts of data,
with appropriate backups and redundancies to ensure data integrity and availability.

3.4 Presentation of use cases

3.4.1 Presentation of actors

In a use case diagram, an actor represents a role or a type of user who interacts with
the system being modeled. Actors are external to the system and may be human or non-
human, such as other software systems or devices.
Online Users :Users who are comfortable with technology and can register for an account
on the system, log in, and submit requests electronically.
In-person Users : Users who prefer to submit their physical documents to the town hall
office and receive assistance from an agent.
Town Hall Agents : Agents who work at the town hall office and interact with both online
and in-person users. They use the system to scan users’ ID cards, retrieve their profiles
and history, generate QR codes for their documents, and manage the document processing
workflow.
System Administrators : Users who manage the system and its resources, including user
accounts, service requests, and document processing. They also monitor the system’s
performance, security, and availability, and ensure that it meets the needs of its users.

3.5 Use case description

3.5.1 Use case : log in

Citizen log in

Table 3.1: Description of the ”log in” use case for citizen

Brahim Karoui 31
Chapter 3 Requirements

Case number 01
Actor(s) Citizens
To enable citizens to create an account on the mobile app, which will allow
Objective
them to submit requests to the town hall system.

Pre-condition(s) The citizen has been registered in the system by an agent.

Post-condition(s) A new citizen account is created in the system.

The citizen opens the mobile app and accesses the registration page.
The citizen enters their personal information and the identification number
provided by the agent.
main scenario The citizen creates a username and password for the account.
The system verifies the information and creates a new account.
The system displays a confirmation message.
The citizen can now log in to the mobile app using the new account.
If the citizen provides invalid information or there is an error in the
Alternative registration process, the system displays an error message indicating the issue
scenario and prompts the citizen to correct it before submitting the registration form
again.

3.5.2 Register citizen

Table 3.2: Description of the ”log in” use case for citizen

Brahim Karoui 32
Chapter 3 Requirements

Case number 02
Actor(s) Agent
To enable the agent to register a citizen in the system, allowing them to
Objective
create an account in the mobile app to send requests to the town hall system.

Pre-condition(s) The agent must be logged in to the system.

The citizen’s personal information and identification number are stored in
Post-condition(s) the system.
The citizen can now create an account in the mobile app.

The agent initiates the ”Register Citizen” use case and enters the citizen’s
personal information and identification number in the system.
The system verifies the information and generates a unique identification
number for the citizen.
main scenario
The system stores the citizen’s information and identification number in the
system database.
The agent informs the citizen that they can now create an account in the
mobile app.
If the citizen’s information is invalid or incomplete, the system displays an
error message indicating the issue and prompts the agent to correct it before
submitting the registration form again.
Alternative
If the citizen’s identification number is already registered in the system,
scenario
the system displays an error message indicating that the citizen is already
registered and prompts the agent to verify the information or contact the
system administrator for assistance.

3.5.3 Register agent

Table 3.3: Description of the ” regester agent” use case for citizen

Brahim Karoui 33
Chapter 3 Requirements

Case number 03
Actor(s) Admin
To enable admin to create an account for agents in the system, which will
Objective provide them with the necessary access and permissions to handle citizen
requests.

Pre-condition(s) The admin has access to the registration functionality.

Post-condition(s) A new agent account is created in the system.

The admin accesses the registration page for agents.

The admin enters the agent’s personal information, such as name, address,
phone number, etc.
main scenario The admin creates a username and password for the agent account.
The system verifies the information and creates a new account.
The system displays a confirmation message.
The agent can now log in to the desktop app using the new account.
If the admin provides invalid information or there is an error in the
Alternative registration process, the system displays an error message indicating the issue
scenario and prompts the admin to correct it before submitting the registration form
again.

3.5.4 Submit Electronic Request

Table 3.4: Description of the ” submit Electronic Request ” use case for citizen

Brahim Karoui 34
Chapter 3 Requirements

Case number 04
Actor(s) Citizen
Objective to enable citizens to submit electronic requests for town hall services.

The citizen is registered and logged in to the system. The citizen has an
Pre-condition(s)
active electronic wallet with sufficient funds.
The citizen’s request is submitted successfully. The wallet funds are deducted
Post-condition(s)
accordingly.

the citizen logs in to the system.

The citizen selects the type of service they need.
The system displays the service fee and the available balance in the
citizen’s electronic wallet.
The citizen confirms that they have sufficient funds in their wallet to pay for
the service.
main scenario The citizen fills out the necessary information and uploads any required
documents.
The system deducts the service fee from the citizen’s wallet.
The system submits the citizen’s request.
The system displays a confirmation message with the request details and the
remaining balance in the citizen’s wallet.
The citizen logs out of the system.
Alternative insufficient funds in the citizen’s electronic wallet Missing or incomplete
scenario information.

3.5.5 ...

Table 3.5: ....

Brahim Karoui 35
Chapter 3 Requirements

Case number 05
Actor(s) Agent
Efficiently process agent documents while ensuring accuracy and providing
Objective
necessary documentation to citizens.

The agent is logged into the system.

Pre-condition(s)
The citizen has submitted a document for processing.
For online citizens:
The system displays a list of pending documents awaiting processing.
The agent selects a document from the list.
The system retrieves the document details and displays them to the agent.
The agent reviews the document for completeness and accuracy.
If the document is complete and accurate, the agent marks it as processed
in the system.
The system generates a QR code for the document.
The agent sends the digitally processed document with the QR code attached
to the citizen electronically
For physical citizens:
a. The physical citizen goes to the town hall and asks the agent to process
Post-condition(s)
their request.
b. The agent verifies the identity of the citizen by scanning their ID card
using the system.
c. The system retrieves the citizen’s profile and history associated with the
submitted document.
d. The agent reviews the document for completeness and accuracy.
e. If the document is complete and accurate, the agent marks it as processed
in the system.
f. The system generates a QR code for the document.
g. The agent prints the document with the attached QR code.
h. The agent hands over the printed document to the physical citizen.
The system updates the status of the document as processed.

Brahim Karoui 36
Chapter 3 Requirements

Alternative The document is marked as processed in the system.

scenario The citizen receives the printed document with the attached QR code.

Figure 3.1: Use case diagram

Brahim Karoui 37