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
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-clithe configuration is stored invue.config.jsandvue-cliwill execute webpack/babel/etc for you. The configuration can be kept invue.config.js(e.g. we don't have webpack elsewhere) or in an external file (e.g. we have babel configuration inbabel.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 theVListwill be automagically imported. In theory it should support tree-shaking too, but both Vuetify and Lodash were never very well trimmed.
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.
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: