1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
|
---
geometry: margin=1in
---
# PROJECT Design Documentation
## Team Information
- Team name: Jelly Solutions
- Team members
- Ben Almstead
- Tyler Ferrari
- Hayden Hartman
- Akash Keshav
- Angelina Zhen
## Executive Summary
Our project is intended to create a space to fund aquatic conservation, from physical ecosystems such as coral reefs to aquatic creatures such as jellyfish. Users will be able to donate funds, both physical and monetary, to individal 'needs', and see how close to reaching a funding goal each need is. Admin accounts can manage needs for the helpers to contribute to. We have a focus on a quality, with a uniform user experience across all features of the site, regardless if a user is a helper or an admin.
### Purpose
The purpose of this project is to provide an avenue for individuals to help support ocean conservation, with helpers donating physical goods and money to support efforts and managers creating and editing needs to
### Glossary and Acronyms
| Term | Definition |
| -------------- | ---------------------------------------------- |
| SPA | Single Page |
| Need | Element to donate to |
| Contribute | Donate |
| Checkout | Pay / Support |
| DAO | Document Object Model |
| Component | UI Element |
| Models | Structure / Laypout |
| Helper | Contributor / User |
| Manager | Administrator |
| Modal | Pop-up page |
| Toast | On-screen notification |
| API key | Token unique to a sesssion for API interaction |
| JS | Jelly Sollutions |
| Funding basket | User's needs |
## Requirements
This section describes the features of the application.
The requirements for this u-fund project to be functional include a system for organizations (administrators) to create funding goals (needs) that can be satisfied by clients (users).
#### Uniform Application Design
All pages and components should be consitent in style and layout. The user experience should be consistent across pages. Everything should be clear and consistent for usability, especially if a user is unfamilliar with our site. Usabilty options should consistently apply, such as different layouts, light/dark mode, or different devices across all pages and components.
#### Layout Information Priority
The most relevant information should always be presented first or be the most visually attracting. Sorting should be able to be controlled by the user in order to access the most relevant information in the cleanest way possible. The layouts should be consistenet across all pages.
#### Security
Users should only be able to acess API functions that match their user type. When a helper acesses an admin only feature, page or command, they should be re-directed or denied access. API commands are verified through the authentication service, with the API key per session granting access to the commands. This prevents anyone from accessing or modifying data they should not have access to.
#### Services and Abstractions
Common code and features should be consolidated into services and classes in order to limit repeated functionality. Classes are abstracted where possible, increasing reusability and code quality across the frontend and backend. All components should use the services as much as possible to keep the code clean and understandable for matinence and bugfixing.
### Definition of MVP
Users are able to login to the Ufund, either as a manager or helper. They can create secure passwords for account security. Helpers are able to go to the cupboard and can view needs, search for needs, add/remove needs to their funding basket, and check out and fund needs. Managers can add, remove, and edit needs in the cupboard. When editing needs, managers can edit one or more properties and update needs for users. Needs have many properties including images, descriptions, goal types and amounts. Needs are saved so users and managers will see when they are updated. Managers can view stats on a managment page.
### MVP Features
- AS a Developer I WANT to create a funding basket component SO THAT needs can be viewed within the cupboard on the dashboard.
- As a user I want to see a homepage so that I can navigate the site.
- AS a User I WANT to see a home page when visiting the site SO THAT I can easily navigate through pages.
- AS a Developer I WANT implement basic, functional CSS for components and pages SO THAT there is basic formatting that can be navigated.
- AS a Developer I WANT to have a cupboard component SO THAT I can display the needs from the cupboard in the UI
- AS a developer I WANT to create data storage for users SO THAT users are able to login to the website through the login page.
- AS a Developer I WANT to create a need page component SO THAT users can view a singular need in an entire page.
- AS a Developer I WANT to submit a request to input a username SO THAT each unique user can access their saved needs.
- AS a user I WANT to see images to needs SO THAT I can get a better idea of what I’m donating to.
- AS a manager I WANT to see a list of statistics about the UFund SO THAT I can manage the ufund better.
- AS a user I WANT to see a clear and navigable login page SO THAT I can easily login or create a new account.
- As a user I WANT to enable light/dark mode to increase usability based on user preferences.
- AS a Manager I WANT to submit a request to edit an existing need through the existing need-list-component, SO THAT it is added to the cupboard in a consistent way.
- AS a Developer I want api keys to be removed when expired SO THAT hundreds of expired keys do not pile up.
- As a user I want to put in my password so that my account is secure.
- AS a user I WANT to see a simple signup page SO THAT I can easily create an account without confusion.
### Enhancements
Security
- We have implemented a set of security features to enhance the security of the application
- We have added an authentication system, which verifies a user can access the correct pages, and keeps them logged in after they have logged in once
- Users cannot access funding basket or dashboard unless logged in
- Helpers cannot access the manager dashboard
- Managers cannot access funding basket
- We have also added a number of password requirements to our signup page, guaranteeing users have strong passwords to keep their accounts secure
- Passwords must be 6 characters or longer
- Passwords must have one symbol
- Passwords must have a number
- Passwords must have an uppercase letter
- Passwords must have a lowercase letter
Sort filters
- We have implemented a number of sorting filters in the cupboard, allowing users and managers to easily sort through needs with different priorities
- You can sort by funding goal
- You can sort by Location
- You can sort by name
- You can sort by an urgency tag on needs
- You can sort by type of need
- You can sort by most completed
## Application Domain
This section describes the application domain.
Each user views 1 cupboard which can contain 0 or more needs. They can take 1 or more needs and put them in their funding basket which they can then check out. Each user has 1 funding basket. 1 manager will manage the 1 cupboard, add, removing, and editing needs within it. Needs have two or more properties. Managers cannot interact with the 1 funding basket each user has.
## Architecture and Design
This section describes the application architecture.
The application is seperated into three tiers. These include the view, viewmodel, and model tiers. The view tier has many angular components, including the cupboard, dashboard, funding basket, homepage, login, mini-cupboard, need-edit, need-list, and toast. These are all used through angular to serve a UI application through the browser. This browser connects through the Viewmodel tier using a REST API. The API is instantiated through springboot. The API uses controllers and services to perform opertaions on the data and return values back to the view tier. The model tier contains the structure of objects, such as needs or users and the persistence of the system. The persistence uses DAO's, or data access objects. These are abstracted classes that can be further defined to interact with databases, files, or other objects. Currently, all the persistence is handled through JSON files through file DAOs.
### Summary
The following Tiers/Layers model shows a high-level view of the webapp's architecture.
The web application is built using the Model–View–ViewModel (MVVM) architecture pattern.
The Model section contains our back-end structure, split into three sections: Model, Persistence, and Controller. Each of the files contained for each section are below each item.
The View is the client-side SPA built with Angular utilizing HTML, CSS and TypeScript. The ViewModel provides RESTful APIs to the client (View) as well as any logic required to manipulate the data objects from the Model.
Both the ViewModel and Model are built using Java and Spring Framework. Details of the components within these tiers are supplied below.
### Overview of User Interface
This section describes the web interface flow; this is how the user views and interacts with the web application.
When a user first visits the website they will arrive at our home page. This gives some info about us and leads them to the cupboard where they can views needs. When viewing a need a user will be prompted to login, or they can click on login at the top right at any time. Once at the login page they can either login or click signup to go to the signup page and create an account. Either page will log the user into the website and bring them to the page they were previously on. Once logged in as a helper a user can view and add needs to their funding basket, letting them checkout and contribute to funding. Otherwise, a user can login as a manager, where they have access to the cupboard and dashboard. In the dashboard they can view information about the website. On the cupboard a manager has the option to control needs, such as adding news ones or editing/deleting existing news.
Home Page:
Login Page:
Signup Page:
Dashboard:
Cupboard:
Need page:
Funding basket:
Our improvements would be to make the website mobile accessible, allowing anyone to access it easily from their phone.
### View Tier
As following our UI description, our view tier has a similar flow. There is a component for the home page when first visiting the page, having basic html to showcase the website. From there, users can go to the login and signup pages which are individual components. They contain the logic to log users in and create an account. Additionaly, signup contains logic to check password strength and make sure a user creates an account with a strong password. Next, a user can visit the cupboard component. The cupboard component uses the need list component which shows a lists a needs. Similar, the funding basket uses the need list component to display needs. When a need is clicked on a user can view the need page component, which displays more info about a need. As a manager, a user can view the dashboard. The dashboard contains info about money raised and users, as well as uses the mini-need-list which can be populated with a list of needs, in this case it's used to display top needs. Additionally, the toast and modal components are used across pages, to display error/info messages and allow managers to edit/create needs.
Sequence for checking out a need:
Sequence for adding needs to the funding basket:
### ViewModel Tier
Controllers
- AuthController: Handles http requests to login and logout users, calling to the authService
- CupboardController: Handles http requests to interact with needs, calling to the cupboardService
- UserController: Handles http requests to interact with users, calling to the userService
Services
- AuthService: Handles logging in and out, as well as authenticating users when they try and visit pages.
- CupboardService: Handles all logic dealing with needs, verifying inputs and throwing errors.
- UserService: Handles all logic dealing with users, verifying inputs and throwing errors.
Requests are sent from the view tier and handled by controllers. For example, when creating a new need a POST request is sent from the frontend and caught by the cupboardController. The cupboardController first authenticates the user, calling the authService and making sure the user has proper access. Next, the cupboardService is called to create a need. The cupboardService checks for a valid goal and name, and then creates a need from the model tier, returning back up. The cupboardController and userController all call authService to authenticate users.
### Model Tier
Models
- Need: A need contains information pertaining to donating, such as a goal and current donations, as well as additional information to provide specifics for each need
- User: A user represents a single account on our website, containing info like a username and a hashed password as well as other fields for specifics
- UserAuth: A user auth is created whenever a user logs into the website, associating a username to a key. UserAuths are used to verify if a user has access to a CRUD operation
Persistence:
- CupboardDAO: Stores needs, allowing CRUD and other basic operations on needs
- UserDAO: Stores users, allowing CRUD and other basic operations on users
- UserAuthDAO: Stores UserAuths, allowing CRUD operations and basic operations on userAuths
In our model tier we have a Need class, a User class, and a UserAuth class. The Need class represents needs and has fields for all of their values. Users have a passwordHash field, storing a hashed version of their password, an List of integers, representing the ID's of needs in the basket, and the userType which determines their privileges. The UserAuth class stores a key, a username, and expiration. A key is generated for a user and is used to authenticate the user. The username is the name associated with the key and the expiration is how long until the user must login again.
## OO Design Principles
- Law of Demeter: Classes only talk to nearby classes.
- The Law of Demeter is present when viewing our architecture, as our MVVM architecture has different tiers, from controllers, to services, all the way to the DAOs. Each tier only talks to nearby layers and never interacts too far. A `CupboardController` never interacts with the `CupboardDAO`, ensuring low coupling and a seamless architecture.
- Low Coupling: Limit the number of classes connected to each individual class.
- Low Coupling is present in our design when viewing the ViewModel tier, as controllers only talk to their own services as well as `AuthService`. Services have minimal interactions with other services and their own DAO's, demonstrating that our architecture is present in our implementation. No class has that bad of coupling, with `AuthService` having the most but it could be changed to only interact with controllers.
- Pure Fabrication: Using helper functions to split up larger classes into more managable chunks.
- For example, this principle is showcased in our `AuthService`. Instead of having services handle authorization, we have split the authorization part into a new AuthService class to handle login and authorization, while the other services handle just the CRUD operations pertaining to the their respestive function. These classes are located in the ViewModel Tier.
- Single Responsibility: Each function should only have one function to prevent unintended errors.
- This principle is present in our controllers, as they only handle communication between the front and back end, letting the services deal with logic and error handling. For example, in `CupboardController`, it's methods only deal with handling back end calls for needs and passing the calls to the services, where they check for faulty values and other issues with need creation, editing, etc.
## Static Code Analysis/Future Design Improvements
- Overall, our results from SonarQube were very good. We had overall good coverage and did not have any major issues. Though we definitely have a number of issues flagged, the majority of them are info, with less than 10 high or medium severity issues. Even then, the major severity issues are fairly minor, such as reusing a string in the field of a thrown error and not putting comments in a nested class.
Some refactoring and improvements we would have made if we had additional time are as follows:
- Improve tests consistency and raise code coverage
- Add more information and create an overall more polished manager dashboard
- Statistics over time
- Radial and progress bars to represent data
- Additional insights on needs
- Add a more robust and accessible image system for needs, allowing managers to upload images instead of using links
- Additional checkout persistence
- Values remaining in checkout fields
- Receipts for checking out
- Deleted needs list and a way to bring back deleted needs
- Filter tags for needs, allowing searching through tags set by managers
### Usability improvement
One area our usability is lacking is on mobile. Below is a mock up of how this would look.
Before:
After:
## Testing
Currently around 115 tests, with roughly 90% coverage overall. Model tier is above 95% individually.
### Acceptance Testing
We have around 40 passing Acceptance Tests. A few tests, such as being logged out after long enough aren't easy to test, as our authentication removes authentications that are over 30 days old. There are probably a few pages and edge cases which are not accounted for in user testing, but have been thoroughly tested through the backend, frontend, or have been individually dealt with.
### Unit Testing and Code Coverage
Our unit testing strategy was to use a consistent styles of test across our persistence tier, model tier, and service/controller tier. On top of this, later on we had a single team member work on the majority of tests, resulting in a consistent style across all of the testing. On top of this, we consistently generated coverage reports and then wrote new tests to cover missing lines/branches. Overall, we had ~95% code coverage with the lowest coverage of a class being 82%. Our model tier was above 90% coverage.
## Ongoing Rationale
**(2025/02/12): Sprint #1: Decided on the U-fund theme as Aquatic / Coral Reef.**
**(2025/02/15): Sprint #1: Outlined structure of Back-End Application.**
**(2025/03/17): Sprint #2: Decided on Important Stories for Sprint 2 Backlog, and reworked Design Architecture.**
**(2025/04/03): Sprint #3: Unanimously decided on enhancements, while narrowing focus on what needs to be finished for the sprint.**
|
