Research: Future DAMAP frontend architecture #473
Description
This issue describes our current research work as to how the future architecture of the DAMAP frontend should look like.
Background
The current DAMAP frontend codebase consists of roughly 20,000 lines of code, which is unjustifiably large for a tool that is one, admittedly complex, form and a list view. Universities are expected to take this code and customize it for their installation, which means they need an on-staff developer who can keep track of DAMAP releases and adjust their customizations accordingly.
While @lpandath has provided us with a very well-written blueprint for limiting the potential blast radius of code changes and making it easier to implement customizations by creating well-defined APIs, currently only TU Wien and TU Graz are maintaining customizations for themselves and on behalf of other institutions. Our conversations with potential institutions wishing to adopt DAMAP for their uses has shown that there is very little appetite for having on-staff developers who need to constantly adapt their frontend to changes. Work on other, similarly structured projects has also shown that these customizations tend to lead to inconsistent UI design because the people working on the per-university projects are not UX experts, but rather software developers with little to no experience in UI design. Finally, it is also hard to maintain accessibility standards (both theoretical, like WCAG and practical by testing with screen readers and other assistive devices) if universities are left to figure accessibility out on their own for their custom components.
We have already taken steps to create a more unified DAMAP installation, such as integrating the Elsevier Pure CRIS system directly. Having these integrations work without the need to modify and recompile the source code will make on premises deployments significantly easier, especially when Kubernetes is involved, for which we now have automated Helm chart deployments.
In parallel, we are also pursuing a shared instance deployment on ARI&Snet so users of academic institutions can simply log in with their eduID or ORCID ID and start creating DMPs without any deployments needed.
We should explore creating a frontend architecture that allows institutions to apply customizations without the need of software development work, purely by configuring these customizations using the admin interface or by providing a schema description for form fields.
University requirements
As far as we can tell, universities have the following requirements when it comes to frontend customizations:
- Changing the name of the tool
- Changing the logo on the login page and in the tool
- Adapting colors (primary, secondary, etc)
- Changing explanation texts inside the form
- Changing supplementary texts, such as privacy policy, etc.
- Adding new fields to the form
- Creating a custom template for document output (not a frontend consideration)
Prior work
As a work on his thesis, @DanceaVlad has created a project exploring the possibility of creating a fully dynamic document store based on JSON Forms that would allow full customizability of document structures. One of the schemas used in this experiment was the RDA DMP Common Standard JSON schema, which is the future exchange format between DMP tools.
Research questions
- Is Angular still the right tool? This framework comes with "batteries included", meaning it can take care of everything. However, given the expansive codebase we have experienced that Angular itself can be the cause of issues and may require large modifications on upgrades. In recent years, browsers have added support for shadow DOM and custom HTML elements, which together make up the concept of webcomponents. Therefore, we have to ask ourselves the question if using a heavy-weight framework like Angular is still justifiable for a tool that is, for all intents and purposes, one form and one list view. Preact and other, more light-weight frameworks should also be considered.
- Should we use a Single Page App (the entire page being controlled by one JavaScript application), or should we create separate apps for the form and list view? While SPAs have a benefit when it comes to managing large and complex data, none of that applies here. As mentioned before, we have one form and one list view.
- How should we handle authentication? Currently, the authentication is performed using the authorization code OIDC flow with PKCE, which is somewhat duplicated between the frontend and backend. Is there a way to relegate this completely to the backend so we can reduce complexity in the frontend? This is especially relevant since we want to support multiple authentication providers in parallel, such as ORCID, eduID, and institutional authentication.
- How do we create and maintain a consistent user interface appearance? The current form has organically grown over the years, without any consistent user interface design. Spacing between elements is fairly arbitrary, custom styles being applied on a per-element basis (for example here). Is there a way to apply a consistent set of rules and make it harder to apply per-component styling and spacing, which is hard to maintain in a consistent fashion? Does applying this make maintenance easier?
- Can we ensure accessibility? This goes for both theoretical accessibility, such as WCAG 2 as well as practical testing with assistive devices such as the widely used NVDA screen reader. This is especially important since most if not all of our users are state-funded educational institutions that have a legal mandate to provide accessible services. (Likely references: Universitätsgesetz 2002, Bundes-Behindertengleichstellungsgesetz)
- How much can we cut from the frontend? Assuming we can move a lot of data, such as list of licenses, which are currently hard- and hand-coded in the frontend, to either the backend to query via an API, or to auto-generated code using OpenAPI code generators, can we cut the maintenance burden on the frontend side?
- Do we recreate the frontend or refactor the current one? Given the amount of refactoring that would be needed on the current codebase, it might be easier to recreate it from scratch.