swt23w23/src/main/asciidoc/developer_documentation.adoc

// SPDX-License-Identifier: Apache-2.0 AND AGPL-3.0-or-later
// SPDX-FileCopyrightText: 2015 Sven Seemann
// SPDX-FileCopyrightText: 2015 Oliver Drotbohm
// SPDX-FileCopyrightText: 2019 Daniel Schoenicke
// SPDX-FileCopyrightText: 2023 Markus Hamann
// SPDX-FileCopyrightText: 2023 swt23w23
[options="header"]
[cols="1, 3, 3"]
|===
|Version | Date of modification   | Author
|1.0     | 29.10.2023          | swp23       | Erste Version
|===

= Developer documentation

== Introduction and goals

== Task definition

As our client Mr Wurst has built up the large catering service Mampf over the years, he now needs a system that will simplify planning for him and his customers. The catering service should enable him to process all billing, ordering and administrative tasks in a standardised way. Previously, Mr Wurst used various programmes for this and was always annoyed by their incompatibility with each other and the additional work involved in separate data storage. He gave us the following description of his small company as a basis for the system development:

The company is divided into four business areas. Event catering provides catering for large events, whether in the form of a buffet or a gala dinner. On request, Mampf can also organise the entire event, i.e. in addition to the food and drinks, decoration, equipment (i.e. crockery, tablecloths, etc.) and staff are also provided, whereby the customer must of course pay rental fees and staff costs in addition to the actual price for food and working hours. The party service supplies private celebrations with cold platters - from weddings and funerals to garden parties and grandma's 75th birthday. There are fixed prices depending on the offer and number of people (e.g. ham platter for 5 people at EUR 20, cheese platter for 3 people at EUR 12.50, etc.) and special offers (e.g. sushi evening for 10 people). A speciality of Mampf is Mobile Breakfast - a mobile breakfast service for smaller companies without their own canteen. Employees can buy a selection of breakfast options (sandwiches, muesli, coffee and tea, etc.) at their workplace at set times. The companies book the offer on a monthly basis. However, planning this offer is problematic - a cost-saving solution (e.g. in the form of pre-ordering) is currently being sought. Mampf's fourth offer is also becoming increasingly popular with customers: Rent-a-Cook. This involves hiring out kitchen and service staff to private households, for example to impress the host's boss with culinary delights. Customers have to take care of the food themselves.

The most important functions that the system should include are to support customer management, take over staff management and allocation, plan appointments, manage accessories (decoration, equipment), determine food requirements (number of dishes/plates/served sandwiches, quantity of drinks in litres), simplify invoicing to customers and facilitate all billing. However, food procurement does not have to be considered. In the end, the catering service should be fully functional and include all the functions already mentioned. The aim is to use centralised data management to make processes more efficient, especially planning within the company. The system should be easy to expand in order to open up new business areas.

The client made the following statements verbally on request:

Customers must be able to register themselves, book orders and delete their account if necessary. The latter should also be possible for the administrator for any customer. The administrator also has special overview pages for managing the business. Orders can only be paid for in cash. The allocation of resources to an order must take place without manual intervention. As part of the special promotions mentioned above, certain offers should have a promotional price and be specially labelled. Bookings for Mobile Breakfast are made on a monthly basis at fixed time slots. There are several menus to choose from. Invoice means an informal list of order items in PDF format and on the website. Billing refers to an informal statement of the actual hours worked by employees each month. In technical terms, passwords for user accounts should be stored securely in accordance with current standards.

== Quality demands

Functional Suitability::

This characteristic represents the degree to which a product or system provides functions that meet stated and implied needs when used under specified conditions.

Performance efficiency::

This characteristic represents the performance relative to the amount of resources used under stated conditions.

Compatability::

Degree to which a product, system or component can exchange information with other products, systems or components, and/or perform its required functions while sharing the same hardware or software environment

Usability::

Degree to which a product or system can be used by specified users to achieve specified goals with effectiveness, efficiency and satisfaction in a specified context of use.

Reliability::

Degree to which a system, product or component performs specified functions under specified conditions for a specified period of time.

Security::

Degree to which a product or system protects information and data so that persons or other products or systems have the degree of data access appropriate to their types and levels of authorization

Maintainability::

This characteristic represents the degree of effectiveness and efficiency with which a product or system can be modified to improve it, correct it or adapt it to changes in environment, and in requirements.

Portability::

Degree of effectiveness and efficiency with which a system, product or component can be transferred from one hardware, software or other operational or usage environment to another.

The following table shows what quality demands have to be fulfilled to which extent.
The first column lists the quality demands, while in the following columns an "x" is used to mark the priority.

1 = Not Important ..
5 = Very Important
[options="header", cols="3h, ^1, ^1, ^1, ^1, ^1"]
|===
|Quality Demand           | 1 | 2 | 3 | 4 | 5
|Functional Suitability   |   |   |   |   | x
|Performance efficiency   | x |   |   |   |
|Compatability            | x |   |   |   |
|Usability                |   |   |   | x |
|Reliability              |   |   |   | x |
|Security                 |   | x |   |   |
|Maintainability          |   |   | x |   |
|Portability              | x |   |   |   |
|===

== Constraints

Each constraint is annotated with b, r and/or u,
each representing if it is a
build-time (includes development),
run-time (backend),
or use-time (frontend)
constraint.
Use-time constraints can be separated into customer (c) and administration (a),
each denoted by having their letter prefixed with `u.`.

=== Hardware specifications

 * r: server computer
 * b: mid-range computer
 * u: computer
 * b: input device for text
 * u: input/output devices
   ** pointing device
     (e.g, mouse, TrackPoint™, digitizer, touch input)
   ** text input device
     (i.e. keyboard),
     can be emulated (software/touch or for accessibility reasons)
   ** u.a: screen with a resolution of at least 1920×1080 at a DPR of 1 (= 96 dpi)
   ** u.c: screen with a resolution of at least 360×640/640×360 at a DPR of 1 (= 96 dpi)

=== Software specifications

 * r: JRE 17
 * b: JDK 17
 * u: Any HTML5/CSS3 compatibly browser using one of the following engines (or a newer version)
   ** Chromium 108
   ** Firefox 115
   ** WebKit 605.1.15
   ** Explicity not supported are any browsers based on Trident/EdgeHTML

=== Product usage

The system is going to to be used as a website for administration and handling of orders for the catering service operated by Hannes Wurst.

The system is supposed to run on a server computer
(a computer running 24/7 with a datacenter-grade internet connection)
so that customers and the administrator can access it at any time.
Its provided service is made available as a web site (HTML5/CSS3/ECMAScript over HTTP).
Should the customer of the project require an encrypted connection using TLS,
it is their responsibility to set up a reverse proxy in front of the system.

It cannot be assumed that the users (customers and administrator) have a technical background,
so common patterns that are easily learned should be used.

== System context
image:models/design/systemContextDiagram.svg[]

== Solution strategy
=== Quality demand fulfillment
[options="header"]
|===
|Quality Demand |Solution approach
|Functional Suitability a|
* *Exchange* Ensure that the exchange of system data between the system component works flowlessly.
* *Requirements* Ensure that all functional requirements as descripted in the contrect are fulfilled.
|Performance efficient a|
*Not important*
|Compatability a|
*Not important*
|Usability a|
* *Language* Ensure that every word on the web interface corresponds to its definition in the industry.
* *Learnability* Ensure that the system can be easily used and understood by its users. This can be realized by e.g. unambiguously describing the content of inputs with labels or tooltips.
* *User error protection / Error handling* Protect user against making errors. Invalid inputs must not lead to invalid system states.
* *User interface aesthetics* Provide a pleasing and satisfying interaction for the user.
* *Accessibility* Ensure that people with a wide range of characteristics can fully use the system. This can be realized by e.g. using suitable font sizes and color contrasts.
|Reliability a|
* *Tests* Add tests to ensure functional integrity.
|Security a|
* *Confidentiality* Ensure that only data can be only accessed by people who are authorized to access them. This can be realized with _Spring Security_ and _Thymeleaf_ (`sec:authorize` - tag).
* *Integrity* Prevent unauthorized modification of data. This can be realized with _Spring Security_ (`@PreAuthorize` - annotation).
* *Accountability* Traceability of actions or event to a unambiguously entity or person. For this application, every `Order` should be linked to a `Customer`.
|Maintainability a|
* *Modularity* Compose the application out of discrete components such that changes of a component have less impact on other components.
* *Reusability* Ensure that components of the system can be reused by other components or systems.
|Portability a|
*Not important*
|===

=== Software architecture
==== Top-Level-Architecture
image:models/design/topLevelArchitecture.svg[]

==== Client-Server-Diagram
image:models/design/clientServer.svg[]


=== Architecture decisions

==== Design Patterns
* Spring MVC

==== Persistence
The application uses *Hibernate annotation based mapping* to map Java classes to database tables. As a database, *H2* is used.
The persistence is deactivated by default. To activate persistence storage, the following two lines in the file _application.properties_ have to be added:
....
spring.datasource.url=jdbc:h2:./db/catering
spring.jpa.hibernate.ddl-auto=update
....

==== User interface
image:models/design/dialogue_map.svg[Dialog Map of the Videoshop]

==== Usage of external frameworks
[options="header", cols="1,2,3"]
|===
|External package |Used by |Why
|org.springframework.boot a|
* catering
| Simple configuration of Spring application
|org.springframework.web a|
* catering
* catering.catalog
* catering.inventory
* catering.order
| Application should be provided as a static website
|org.springframework.security a|
* catering
* catering.inventory
| Security features for the videoshop application and authorization of website access
|org.springframework.data a|
* catering.order
| JPA connection utility to the database layer
|org.salespointframework a|
* catering
* catering.catalog
* catering.inventory
* caterin.orger
* caterin.users
| Reuse of SalesPoints POS functionality
|===

== Building block view
=== Package diagram

Note: In this example project the content package diagram would look like the Top Level Architecture, so it was omitted.

=== Catering

image:models/design/catering.svg[class design diagram - Catering]

[options="header"]
|===
|Class/Enumeration |Description
|Catering|The central application class to configure the Spring container and run the application
|CateringWebConfiguration|Configuration class to route `/login` directly to the `login.html` template
|WebSecurityConfiguration|Configuration class to set up basic security and login/logout options
|===

=== Catalog
image:models/design/catalog.svg[class design diagram - Catalog]
[options="header"]
|===
|Class/Enumeration |Description
|CatalogController |A Spring MVC Controller to handle requests to show ``Product``s
|CatalogInitializer |An implementation of the DataInitializer to create dummy ``Product``s on application startup
|Consumable,Rentable| Extensions of ``Product`` to describe offered Products more precise
|ConsumableCatalog, RentableCatalog| An extension of Salespoint.Catalog to add catering specific queries
|===

=== Inventory
image:models/design/inventory.svg[class design diagram - Inventory]

[options="header"]
|===
|Class/Enumeration |Description
|InventoryController |A Spring MVC Controller to handle the request to list and mutate the catering service’s inventory
|InventoryInitilalizer |An implementation of the DataInitializer to create dummy data on application startup
|InventoryMutateForm |An class to validate the user input of the edit/add form
|===

=== OrderCatalog

image:models/design/orderCatalog.svg[class design diagram - OrderCatalog]

[options="header"]
|===
|Class/Enumeration |Description
|OrderCatalogController |A Spring MVC Controller to handle the event catalog
|OrderCatalogEntry |A class to save an event pack created by the administrator
|OrderCatalogEntryRepository |A repository to save all event packs in the form of OrderCatalogEntry
|===

=== Order

image:models/design/order.svg[class design diagram - Order]

[options="header"]
|===
|Class/Enumeration |Description
|OrderController |A Spring MVC Controller to handle the cart and all orders
|CustomOrder |An extension of `Order` to save the start and finish of an event
|ProductForm |A Form to cache a user input that was made while planning and event
|===

=== User

image:models/design/user.svg[class design diagram - User]

[options="header"]
|===
|Class/Enumeration |Description
|Usercontroller |A Spring MVC Controller to handle profile management.
|UserDataInitalizer |An Initializer with primary purpose to add the admin.
|UserManagement |A class that manages the UserRepository.
|UserRepository |An extension of 'CrudRepository' to store Users.
|User |A class that allows a person to associate system data with themselves.
|UserForm |A Form to cache a user input that was made during registration or updating the profile.
|FormValidator |A validator that validates the UserForm.
|===

=== Staff

image:models/design/staff.svg[class design diagram - Staff]

[options="header"]
|===
|Class/Enumeration |Description
|Employee |A class that represents employees (staff members). It includes name, job type and an ID.
|StaffController |A Spring MVC Controller for handling staff-related operations such as adding, removing, and updating staff data. It interacts with StaffManagement.
|StaffManagement |A class that manages interactions and logic with StaffRepository. It provides methods to find, save/add, list, and delete staff members.
|StaffRepository |An extension of 'CrudRepository' that provides standard methods to perform CRUD operations on staff objects.
|StaffForm |A Form to cache a user input that was made during registration or updating an Employee.
|===

=== Link between analysis and design


[options="header"]
|===
|Class/Enumeration (analysis) |Class/Enumeration (design)
| Inventar | org.salespointframework.inventory.UniqueInventory
| Auftrag | catalog.order.CustomOrder
| Nutzer | catalog.users.User
| Kunde | Is a role of Nutzer
| Admin | Is a role of Nutzer
| Leihmaterial | catering.catalog.Rentable
| Verbrauchsmaterial | catering.catalog.Consumable

|===

== Runtime view

=== Catalog
image:models/design/seq_catalog.svg[sequence diagram - catalog]

=== User
image:models/design/seq_users.svg[sequence diagram - user]

=== Inventory
image:models/design/seq_inventory.svg[sequence diagram - inventory]

=== Order
image:models/design/seq_order.svg[sequence diagram - order]