(2) How to Develop
This chapter explains the structure of the project, which libraries are used and how specific functionalities work. The application uses the following technologies:
- Client
- Typescript as programming language.
- React.js as library for web-based user interfaces.
- Vite as development environment.
- MaterialUI as React component library.
- Server
- Python as programming language.
- Django as web framework.
- PostgreSQL as database.
The project is structured into the following folders:
- .github: This folder contains all files for the github workflow.
- client: This folder contains all files regarding the client.
- docker: This folder contains the dockerfiles for the client and the server.
- letsencrypt: This folder contains the necessary files to create certificates for the web application
- server: This folder contains all files regarding the server.
This section provides an overview of the client's folder structure inside the ./client/src folder.
- /api: This folder contains files to send and receive requests from the server.
- /assets: This folder contains static images.
- /components: This folder contains the components displayed to the users. The folder is divided into the main components which are also divided into subfolders for the sub components.
- /constants: This folder contains files with static values such as the themes with the defined colors.
- /helpers: This folder contains helper functions for other files.
- /services: This folder contains files to process the server responses from the /api files and handle errors. The components can directly use the functions in this files to access or manipulate the data.
- /states: This folder contains all global variables of the client. The files define the global variables and initialize them with a default value on startup.
- /types: This folder contains all custom types for parameters and elements in the components. As the project is using Typescript it is important to create types in order to ensure type saftey.
This section provides an overview of the client's folder structure inside the ./server folder. The server is divided into different applications responsible for a feature of the system respectively. The applications consist of a 'model.py'-file which contains all models necessary for the feature, a 'serializers.py'-file which validates the structure of the data, a 'urls.py' defining the endpoints for the feature and a 'views.py' which orchestrates the requests and creates the responses. Some of the application have a 'service' folder which provides reusable functions for the views.
- /chat: This application contains all models and functionalities for the chats. This includes the chats, messages and labels.
- /deployment_management: This application handles functionalities for the deployment. This includes the creation of a superuser on the deployment if there is no superuser in place.
- /insights: This application contains all functionlities to calculate the metrics shown on the dashboard.
- /interactions: This application contains all functionalities to log the interaction of the users with the system. This includes the model for the EventLog
- /pages: This application contains all models and functionalities for the pages. This includes the pages and tags.
- /templates: This folder contains all static files like the template for activation email in the user registration
- /users: This application handles the registration process of an user including the account creation and the account activation template.
- /server: This application includes all settings of the server. The 'settings.py'-file includes all settings of the server including CORS, database setup etc.
For data fetching and caching we use the React Query library. It simplifies the process of fetching, caching, synchronizing, and updating server-side data, allowing us to handle asynchronous operations more efficiently. React Query offers features like automatic caching, background updates, and request deduplication, which help reduce redundant network requests and enhance application performance. We emphasize the usage of React Query for server requests which occur often and on components which are reloaded regulary. This enables us to keep the load of the server to a minimum.
We use Zustand to manage our global states. The global states can be found in the '/states' folder of the client. It uses a simple store pattern based on JavaScript functions and hooks, allowing you to define your state, update it, and access it from anywhere within your application. If you change a variable please check where the variable is used before to avoid errors and undesired behavior by components.
We use MaterialUI as component library. We recommend to use and customize the provided components in order to keep a consistent system design. For a responsive user interface please use the 'Grid' component. For a consistent font type and size use the 'Typography' component. For icons we use the React Feather library for icons and the Recharts library for charts and graphs.
It is important to use the Error Boundary library when using sub components in a component. This library catches errors anywhere in the child component tree, log those errors, and display a fallback UI instead of the component tree that crashed. Error boundaries help manage errors in React applications by preventing a whole app from crashing due to an error in a specific part of the UI.
We use the default user management provided by the Django framework for the registration, login and role management of users. This also inlcudes the generation of JWT to ensure safe communication between client and server.
We use the OpenAI to generate the responses to the chatbot prompts by the user. The application can only handle textual output. Thus we use the GPT-3.5 Turbo model for the generation.
We use an Microsoft Exchange mailbox to send the account activiation emails to the user. Thereby the environment variable 'DEFAULT_FROM_EMAIL' defined the exchange mailbox from which to send emails. This mailbox is the sender of the emails. To send emails with this library from this mailbox you have to authenticate with an email account which has access to this mailbox. The environment variables 'EMAIL_HOST_USER' and 'EMAIL_HOST_PASSWORD' define the email address and the password of the email account with access to the mailbox.
This image illustrates the subsystem decomposition of the client. The client is developed using the React library with TypeScript and is divided into two layers. The user interface layer manages user interactions with the system, containing all components presented to the user through the interface. The service layer handles communication between the client and the server, enabling the client to send structured and authorized requests to the server.
This image shows the server divided into its subsystems. The server, based on the Django framework, is structured into three layers. The Web Layer provides the system's endpoints to receive requests, defining the REST API. It handles the authorization checks and sends the requests to the corresponding views in the View Layer. The View Layer processes the incoming requests. It handles the logic for interpreting the requests and determining the appropriate response The Model Layer defines the data structure and allows the accessing of the data stored on the database. In line with our goal of achieving a closed architecture, each layer can only access the layer directly below it.
In this section, we discuss how the system manages data persistence throughout its lifecycle. The system utilizes the relational database management system (RDBMS) PostgreSQL, which structures data into tables with defined relationships. PostgreSQL allows for querying and manipulating data using SQL, ensuring efficient and organized data management.
The persisted data can be inserted or manipulated either through the server or directly in the admin panel by a superuser acting as a database administrator. Upon deployment, the system defines an initial superuser to ensure administrative access. This superuser has the authority to create additional superusers as needed.
