Skip to content

Architectural Decision Records (ADRs)

Jump to bottom
Alejandra Gonzalez-Beltran edited this page Jul 19, 2019 · 21 revisions

This page provides all the architectural decisions for the system - this may be decisions where there are multiple valid choices but for certain reasons one option is chosen over the others.

This list of ADRs also retains historical decisions to show how decisions have changed over time and the reason for that change - this prevents cyclical decisions due to knowledge being lost.

Possible status values are proposed, accepted, rejected, deprecated, superseded.

ADRs

1. The frontend technology will be React

Status: accepted

Context: There are multiple frontend technologies available; React, Vue or Angular - one of them needs to be chosen to write the SciGateway frontend and its plugins in.

Decision: React will be the chosen technology for the frontend as it is best suited to large scale apps, has the most community support and combines well with other technologies allowing it to stay current.

Consequences: The SciGateway frontend and any plugins centrally developed will be developed using React.

2. The frontend will be developed with Typescript

Status: accepted

Context: Javascript is an dynamically typed language. Typescript is an extension to the the ECMAScript language specification that strongly types the language.

Decision: We have decided to adopt the Typescript for frontend development. This will add additional development and compile time checks to the code.

Consequences: Additional development overhead.

3. Redux for React App State Store

Status: accepted

Context: Building a complex web application brings challenges around how to manage state.

Decision: We have decided to adopt the Redux architecture to provide a clean separation between our views, actions and state store.

Consequences: No foreseen consequences of this choice.

4. The frontend will use Material-UI components

Status: accepted

Context: There are multiple UI widget libraries available:

Decision: Material-UI will be used for a standard component library.

Consequences: The library

  • implements Google's material design,
  • offers a wide range of standard widgets,
  • has very good online documentation,
  • is actively supported,
  • npm libraries available that offer integration with Redux react-redux
  • is a de-facto industry standard for React UIs

5. Micro-frontends

Status: accepted

Context: The application must support a plugin architecture supporting site-specific front end components. A micro-frontend architecture supports this model bringing in UI elements from local files or remotely hosted sites.

Decision: We have decided to adopt a micro-frontend architecture using the single-spa library.

Consequences: All UI plugins must include a set of hooks defined in the single-spa model:

  • mount
  • unmount
  • bootstrap.

6. Namespaces will be used to partition plugin and parent application events

Status: accepted

Context: Messages are shared between plugins and the parent application via CustomEvents with typeArg of daaas-frontend. The action wrapped by this event is dispatched as a redux action in the parent app, and if the broadcast property is set, in any other plugin that is listening.

The redux action triggered uses the action.type attribute of the event payload.

There is the potential for name clashes between actions defined in plugins for internal use, for consumption by external plugins or by the parent app.

Decision: We have decided that all event actions must adhere to a namespace pattern: <plugin_name|daaas>[:api]:<action_name>.

  • The core API of the parent application will be defined through daaas:api actions.
  • The public API of any plugin must include the :api element.
  • All plugins must be uniquely named.
  • Event names will be underscore_separated_words

Examples include:

  • daaas:api:register_route : plugin registration action, published by the parent app for use by all plugins
  • daaas:toggle_drawer : internal parent application redux event
  • plugin1:api:request : public action owned by plugin1
  • plugin1:process_action : private redux action for plugin1

Consequences: Provided all plugins are uniquely named there can be no conflict of actions triggered by plugins. There is a clear indication whether an event should be handled or ignored. There is no requirement for internal messages to remain consistent between versions however breaking changes to any public action should be well publicised before being made.

7. Material-UI will not be provided as an external library

Status: accepted

Context: One of the drawbacks of micro-frontends is that the overall size can get large if they all include copies of the same library. For this reason the parent app includes a copy of common libraries (e.g. React and ReactDOM) that plugins can use.

Decision: We will not make Material-UI available via the parent app. We tried this and it made the referencing very difficult in the source code (it couldn't use the normal import syntax and had to be accessed from window[material-ui]. The complexity this would have introduced onto plugin developers was deemed to be too great and not worth the space savings at this point in time.

Consequences: All plugins will need to include their parts of Material-UI - this will mean repeated instances of parts of the library and could lead to a large overall bundle size. This should be monitored and this ADR should be revisited if it becomes an issue.

8. Google analytics will be used to track page views and some user actions

Status: accepted

Context: In order to be able to log what users commonly do better than the current TopCAT, we need to log pageviews and any actions that we would like to be able to how they are being used.

Decision: We will use Google Analytics via the react-ga library

Consequences: Google analytics will be used to track pageviews and actions. The application will have to obtain user consent to use Google Analytics. We will not be in complete control of our log data - this decision is to be revisited later on if/when a server side logging mechanism is added.

9. datagateway-table: Downloading files will be performed via a link to the IDS in a new tab

Status: accepted

Context: The current TopCAT uses <iframe> to allow users to download files obtained from the IDS. However, if the IDS call fails then this doesn't provide any feedback to the user. In order to improve the user experience in the failure case, the error must be visible in some way.

Decision: We will instead create an invisible link to the IDS and open it in a new tab. This tab then either disappears and shows the user the download dialogue in the success case or displays the IDS error page in the failure case.

Consequences: The user will be able to see if the download call failed. The error appears in a new tab and our application tab is left as it is. We disrupt the user experience by opening new tabs and showing errors in a new tab. This will be fixed in datagateway-table#3, which will then supersede this ADR.

Clone this wiki locally