Jans UI Architecture - uprightech/jans-admin-ui GitHub Wiki

Janssen Admin UI

1. Introduction

The aim of this document is to outline the architecture of the new Janssen Admin UI. What is to be kept in mind is the pluggability of the entire UI. In the following sections, we will outline a tentative UI wireframe or wireframes, separating each of them into well defined sections which will help determine which areas of the UI are pluggable and which aren't. We will also outline how user interactions are processed by the UI and it's various components.

2. UI Look and Feel

As much as it should be possible to fully customize the UI, a default UI look and feel will be provided. It will consist of :

  • a top header which will display the ui logo , and some user related content
  • a sidebar which will contain menu items used to navigate through the main UI provided functionalities
  • a content area, the largest area , which will be used to display either relevant data to users (dashboard) , or allow the users to view/manipulate data (e.g. adding clients, etc...)
  • a footer to display minor information such as copyright notices, etc ...

Image of default look and feel UI

The default UI look and feel will be further split in two. The dashboard UI look and feel which will be used by any rendering of a dashboard-like nature , and the standard UI look and feel which is used for jans-auth data viewing/manipulation. Subsequent subviews can be introduced to provide even more flexibility to the UI

2.1 Dashboard UI Look and Feel

image of dashboard look and feel UI The dashboard UI's main characteristic feature is the presence of widgets in the content area. The widgets are used to display key performance indicators in the system as well as vital system information (update releases and product news for example).

2.2 Standard UI Look and Feel

image of standard look and feel UI The standard UI wireframe is less specialized than the Dashboard UI wireframe. Instead of being constrained to data (and data related) display widgets as is the case with the dashboard UI. This is because it can't be known beforehand what will be displayed within the content area. This gives greater flexibility to whoever is extending the UI.

3. Pluggable UI components outline

In this section, we will outline what could potentially qualify as a pluggable UI section and by corrolary , what can't be.

3.1 UI Theme

The layout (UI theme) should be pluggable. As much as it won't be discussed in detail here, it's worth mentionning that the idea would be to have plugins export/expose various plugin types (or capabilities) , and the UI theme is supposed to be one. Also , UI theme reresources will need to be exposed (especially for javascript and css resources which won't be really templateable) directly via the webserver. We will have to find a way to dynamically publish such assets.

Each page contains a header which in principle should be pluggable. Not pluggable in the sense that it should be changeable at runtime , but pluggable in the sense that when providing themes/pages, it should be possible to provide the page header(s) as a UI component. It will follow a recurring theme for sub-components where a contract will be established between a data provider, written (mostly) in javascript , and UI renderer , which will be written in a combination of javascript and html (react).

The page footer will follow the same pattern as the page header. The difference is by default , the data provider for the footer will be much more simpler.

3.2 Sidebar

The sidebar is an interesting pluggable UI component. It will contains navigation links that will be used to move accross pages/features within the UI. UI plugins (again) do not need to export one of these , but should be able to export menu item data that will be then used to generate UI menu items that will be displayed on the said sidebar. How this will be done (server side or client side only) will depend on the availability/use of url routing on the client side or the server side

3.3 Page Contents and widgets

Each page will have page contents injected in the provided template. It should be possible for each page contents to be contained within specific classes (typescript) which are dynamically plugged in at runtime , and called upon for rendering (ReactJS). That alongside data that still will be coming from some data provider(s). Widgets , like for example the dashboard widgets ought to be pluggable , and possibly in the near future interchangeable at runtime, meaning it should be possible to choose at any point in time what metrics should be displayed on a dashboard , or even where it will be displayed.

4. Application Deployment Strategy

In this section we will describe a suggestive application deployment strategy.

4.1. Server Side Deployment Strategy

On the server side, the application will be deployed as a war in jetty , behind an Apache HTTP server. The apahce HTTP server and the application will share a directory where web assets can/will be published (css , js , images, etc ... ).

4.2 Client side deployment strategy

Nothing really special on this end, besides an outline (not yet decided fully) of the technologies to be used on the client side.

4. Application LifeCycles

In this section, we will describe various lifecycles that pertain to the application. The list of lifecycles here isn't exhaustive, and can be amended. An outline will be done here, while a sequence diagramm is prepared for each lifecycle.

4.1. Page loading/rendering lifecycle

In this section we will describe the page loading/rendering lifecycle:

  • The user requests a page from the browser
  • The application (server-side) selects the proper UI theme/layout. We will also have to choose an appropriate template engine. More on that later. My personal choice would be thymeleaf (https://www.thymeleaf.org/)
  • The application, through the template engine , injects all of the required resources (css , javascript mostly) published/exported by the application and it's (active) plugins.
  • The (partially rendered) page is sent to the browser
  • The javascript portion of the application takes over and enumerates javascript objects exposed by plugins (where applicable)
  • After enumeration , through exposed methods , the javascript portion of the application initializes the plugins
  • ReactJS is introduced and renders the final parts of the UI

4.2. Plugin Loading lifecycle

This section describes what happens when a plugin is loaded and activated.

  • The plugin management subsystem unpacks the plugin (probably in a zip format)
  • The plugin management subsystem reads the plugin manifest (probably in json format)
  • Important metainformation may then be stored about the plugin in persistence for easy access
  • If there exist plugin resources/assets , they are deployed in the directory being shared by apache and the application
  • The plugin should provide an object that provides a plugin interface. That object will be instantiated through an as of yet discussed method.
  • The plugin's initialization and setup methods methods exposed through the object are to be called
  • Assuming initialization does not fail , the plugin will be marked as "loaded"
  • Through an unspecified (as of yet) means , the client side is notified and a page reload is prompted if required

4.3. Plugin Un-loading lifecycle

This section describes what happens when a plugin is de-activated and un-loaded.

  • The plugin management subsystem takes a look at the plugin manifest and makes a list of resources to delete
  • The plugin management subsystem calls the unload-ing methods on the object exposed by the plugin
  • The plugin management subsystem removes all the assets related to the plugin
  • Through an unspecified (as of yet) means , the client side is notified and a page reload is prompted if required

5. Application Architecture