From 11bbe4408cf3e147a7d2f69d77a9d53b5090a843 Mon Sep 17 00:00:00 2001 From: Amar Bolkan Date: Tue, 8 Nov 2022 15:28:49 +0100 Subject: [PATCH] Issue #151: Restructure ADR --- docs/adr/adr_0005.md | 100 +++++++++++++++++-------------------------- 1 file changed, 39 insertions(+), 61 deletions(-) diff --git a/docs/adr/adr_0005.md b/docs/adr/adr_0005.md index c743642f..48819995 100644 --- a/docs/adr/adr_0005.md +++ b/docs/adr/adr_0005.md @@ -28,42 +28,51 @@ To calculate the score for a specific team the following entities are queried fr - team: `/api/teams` - all available badges: `api/badges` -In the dashboard view this leads to all `Teamskills` (possibly #Teams * #Skills) being loaded into the frontend. -Depending on the number of Teamskills the scores can be incorrect. This happens due to pagination and the client not checking if all records were queried. -This problem has been, until now, avoided by simply increasing the size of each page. +In the dashboard view this leads to all Teamskills (possibly #Teams * #Skills) being loaded into the frontend. -This however is not a long term solution, especially in terms of scalability as the -maximum number of teamSkills can increase quit rapidly. -Therefore, the addition of one single team or skill might push the total amount of records above the currently set maximum for each page. -This leads to several problems. The most severe one is that correct behavior of the systems is depending on the -current amount of data. This calls for more viable solution to be implemented. +#### Problem +Depending on the number of Teamskills the scores can be incorrect. This happens due to `Pagination` and the client `only querying the first page`. +The solution up to this point has been to simply increase the page size. This however is not a long term solution, especially in terms of scalability as the +maximum number of Teamskills can increase quit rapidly. -## Decision +There appear to be two general approaches one of which would be fixing the problem in the frontend and the other to move the entire calculation into the backend. + +### Solution 1: Check if all pages have been queried + +Instead of increasing the maximum amount of entities per page, the client could check if all pages have been queried. +This would ensure that all Teamskills have been retrieved from the backend and in turn should lead to all Teamscores being calculated correctly. + +### Pros + +- low implementation effort, query for Teamskills only needs to be put into a loop +- no new files need to be added / no custom code needs to be changed or extended + + +### Cons -### Solution 1: Moving the calculation into the backend +- keeps the computational load on the client +- `Teamscores` can't easily be queried by third party software +- might negatively impact scalability of the system, due to increasing amounts of data needing to be queried -#### Non-persistent approach -Move team score calculations to the backend and create an Api, which -the client can query. The calculation of the score is done on demand and is not persisted. -Proposed API: +### Solution 2: Moving the calculation into the backend -`/api/team-score/:teamId` : Accepts GET requests and returns the current score for the queried team. +Create a new Service, which queries a backend Api that calculates the score for a team on demand. #### Pros - the new API would allow for third party systems to query `Teamscores`, which would for example enable easy monitoring through something like Prometheus - client performance should increase because calculation is now done server side -- this change might make the score calculation more scalable for each score only a subset of `Teamskills` is queried. - calculating the score on demand avoids having to check after every CRUD operation if the previously calculated score is still correct. #### Cons -- the client for retrieving the score needs to be adapted to the changes -- more java classes need to be added to the backend, these might need to be changed when updating to new versions of the `Jhipster Generator` +- changes need to be made in client code +- custom classes need to be added to the backend. Those might need to be maintained, when updating to new Jhipster versions -Files to be added to the backend: + -#### Cons -- persisted `Teamscores` now need to be maintained (server needs to react when events occur which might influence the `Teamscore`, for example a skill expires or isn't relevant anymore) -- generated code might need to be extended or changed + -### Solution 2: Query all entities - -Another solution would be to keep sending queries until all entities have been returned by the backend. - -### Pros - -- low implementation effort, query for `Teamskills` only needs to be put into a loop -- doesn't add new custom files to the backend, which would need to be maintained separately from the generated ones - - -### Cons +## Decision -- keeps the computational load on the client -- `Teamscores` can't easily be queried by third party software -- might negatively impact scalability of the system, due to increasing amounts of data needing to be queried +We decide to implement Solution 2. The score calculations won't be persisted in the database. ## Consequences -### Solution 1: - -This change would shift the computational load onto the server and provide a clear and easy way for the client to -query scores for each individual team. In turn new classes are added to the backend and the client code also needs to be adapted to use this new Api. -It would also lead to code duplication as `RelevanceCheck` and `CompletionCheck` are also used in different parts of the frontend. - +- Moving the `Teamscore` calculation to the backend will shift the computational load to the server +- Making `Teamscores` queryable through a separate API enables third party systems to monitor `Teamscores` over time +- New files need to be added to the backend and client code needs to be adapted -### Solution 2: +### Persisting Results -This would simply be a small adaption in the client code. Where the single query is replaced -by a loop that checks if all pages have been queried. -In case of large datasets this solution could lead to higher network traffic and be a strain on the -clients resources. +Calculating `Teamscores` only on demand means that the same calculation might be done over and over again. +This could in the future lead to a performance bottleneck and might be further discussed in separate ADR.