Architecture

Diagrams about Cylc UI architecture. Useful for other developers, not intended for wider audience.

• Building blocks
• How are components organized in the UI hierarchy?
• UI Views
• The UI data store
• GraphQL subscriptions

Building blocks

The following diagram illustrates the stack used to build Cylc UI. The main library, although not highlighted in the figure, is Vue. Cylc UI is a ES6 Vue application, built with vue-cli.

NOTE: normally you would be working with the webpack, rollerjs, etc, configuration files. But with vue-cli the configuration is stored in vue.config.js and vue-cli will execute webpack/babel/etc for you. The configuration can be kept in vue.config.js (e.g. we don't have webpack elsewhere) or in an external file (e.g. we have babel configuration in babel.config.js). It's up to the developers to choose.

It is easier to read the diagram from the bottom up.

At the bottom of the stack we have the transpiler Babel, which does things like rewriting const nodeId = node.node?.id (null coalescing operator, not supported in browsers) to something like const nodeId = (node.node) ? node.node.id : undefined. It also transpiles code from libraries like Vuetify (see babel.config.js).

webpack is the bundler used by our code. It coordinates babel, sass, postcss, etc., producing the final files of our application.

It is worth opening the GitHub README.md of each of these building tools, if not already familiar with any of them.

In the middle of the diagram we have libraries. At the top of the libraries panel we have Vue libraries such as Vue, VueRouter (navigation), Vuex (UI data store), and Vuetify (UI framework). These are closely related to Vue. Next we have utility libraries such as lodash (utilities not found in the JS language), graphql (parsing & merging queries), enumify (because ES6 doesn't have enums), and @mdi/js (material design icons for JS). The penultimate row from the top has just mitt (event bus) and Lumino (tabbed layout). Finally, we have the two libraries used for communication. Axios is used for REST (e.g. JupyterHub REST API) and ApolloClient is used for GraphQL (e.g. GraphiQL, mutations, subscriptions.)

At the top of the stack we have the UI components. We used Vuetify to bootstrap the UI development, slowly adding custom components. On the left hand side you have the Vue components we wrote. Some of these components still use Vuetify components and styling (i.e. css).

To the right you have a few Vuetify components that are commonly used.

NOTE: you may not find the imports of Vuetify components, but that's because we have vuetify-loader, which takes care to create the imports on-the-fly as needed. With this, you can simply write <v-list> in your template and the VList will be automagically imported. In theory it should support tree-shaking too, but both Vuetify and Lodash were never very well trimmed.

How are components organized in the UI hierarchy?

This diagram shows an example of how the UI components are organized when you access the route /#/ (the application dashboard) in your browser. Take a look at src/router/index.js to see what else VueRouter is doing. And for the layout, look at the App.vue computed variables.

The VMain component is not in our source code directory. It was left intentionally to show that Alert.vue and Dashboard.vue both share a parent, and also to point that we have several components in the UI structure that are imported from Vuetify.

The best way to visualize the complete list of components and how they are organized hierarchically is using the Vue Dev Utils browser extension. Note in the Vue Dev Utils screenshot below that it displays the same structure above, but with more components.

NOTE: there are two Vue extensions in the screenshot above, one for Vue 2 and one for Vue 3. Pay attention to which version you install. Cylc UI is built with Vue 2.

UI Views

This section revolves around the Workflow.vue view. That view utilizes the Lumino.vue component to show other views in tabs.

NOTE: Cylc 7 had the concept of Views, like the Tree View, the Graph View, the Dot View, and so it goes. In Cylc 8 UI, the Vue framework has the concept of VueRouter's views. To add to the confusion, the Cylc 7 Tree View is implemented as a Vue component, that is used in a VueRouter view. So note that these terms may be used interchangeably.

The Cylc 8 UI views are VueRouter views (although Vue components are also supported) and use mixins to define the expected behavior of views. A view like the Tree view will have the following mixins:

• mixins/index for the page title (this is for when the view is accessed directly)
• mixins/graphql to define the GraphQL subscription variables (e.g. workflowId: some/workflow/run1)
• mixins/subscriptionComponent hooks up the Vue component lifecycle hooks with WorkflowService functions
• mixins/subscriptionView hooks up the VueRouter navigation guards with WorkflowService functions
• mixins/subscription this mixins is used by the two subscription* mixins above, and adds the ViewState state and setAlert function to the view

Each Cylc UI View has a ViewState that may hold the state of NO_STATE, LOADING, ERROR, or COMPLETE. The mixins/subscription has a computed isLoading property that uses the ViewState to return a boolean. The WorkflowService updates the ViewState.

The WorkflowService drives the subscription for the Cylc UI View.

The UI data store

This diagram gives a high level overview of the Cylc UI data store (Vuex states only).

To understand how Vuex works, what are states, actions, and mutations, it is recommended the reading of the following Vuex docs sections:

1. Introduction - Getting Started
2. Core Concepts - State
3. Core Concepts - Getters
4. Core Concepts - Mutations
5. Core Concepts - Actions
6. Core Concepts - Modules

GraphQL subscriptions