Skip to content

Architectural Decision Records (ADRs)

Jump to bottom
Nick Battam edited this page Apr 1, 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 DAaaS 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 DAaaS 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.

Examples include:

  • daaas:api:register_route : plugin registration action, published by the parent app for use by all plugins
  • daaas:toggledraw : internal parent application redux event
  • plugin1:api:request : public action owned by plugin1
  • plugin1:processaction : 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.

Clone this wiki locally