Architecture 12 - Galaxy Client Architecture

</span></div>

</span></div>

---

# Architecture 12 - Galaxy Client Architecture

<div class="contributors-line">
		<a href="/training-material/hall-of-fame/jmchilton/" class="contributor-badge contributor-jmchilton"><img src="/training-material/assets/images/orcid.png" alt="orcid logo" width="36" height="36"/><img src="https://avatars.githubusercontent.com/jmchilton?s=36" alt="John Chilton avatar" width="36" class="avatar" />
    John Chilton</a>
	</div>

</div>

<div class="footnote" style="bottom: 8em;">
  <i class="far fa-calendar" aria-hidden="true"></i><span class="visually-hidden">last_modification</span> Updated:   
  
</div>

<div class="footnote" style="bottom: 5em;">

<i class="fas fa-file-alt" aria-hidden="true"></i><span class="visually-hidden">text-document</span><a href="slides-plain.html"> Plain-text slides</a> |

</div>

<div class="footnote" style="bottom: 2em;">
    <strong>Tip: </strong>press <kbd>P</kbd> to view the presenter notes
    | <i class="fa fa-arrows" aria-hidden="true"></i><span class="visually-hidden">arrow-keys</span> Use arrow keys to move between slides

</div>

???
Presenter notes contain extra information which might be useful if you intend to use these slides for teaching.

Press `P` again to switch presenter notes off

Press `C` to create a new window where the same presentation will be displayed.
This window is linked to the main window. Changing slides on one will cause the
slide to change on the other.

Useful when presenting.

---

### <i class="far fa-question-circle" aria-hidden="true"></i><span class="visually-hidden">question</span> Questions

- How is the Galaxy UI built?

- What frontend technologies does Galaxy use?

- How do I develop and test the client?

---

### <i class="fas fa-bullseye" aria-hidden="true"></i><span class="visually-hidden">objectives</span> Objectives

- Understand the client build process

- Learn about Vue.js and Vuex

- Navigate the client source code

- Run client tests and development servers

---

# Architecture 12 - Galaxy Client Architecture

*The architecture of Galaxy's web user interface.*

---

layout: true
name: left-aligned
class: left, middle
---
layout: true
class: center, middle

---

### Client Architecture

*The architecture of Galaxy's web user interface.*

---

### Client Directories

- Source JavaScript for the client is in `client/src`.
- Source stylesheets are in `client/src/style`.
- "Packed" bundles served by Galaxy stored in `static/dist`
  - `run.sh` uses `git diff` to try to determine if client needs to be built before starting Galaxy
  - webpack builds these "compiled" artifacts

Upshot - to develop against the client, modify files in `client/` and rebuild with `make client` before
deployment.

---

### Building the Client - Makefile Targets

```Makefile
client: node-deps ## Rebuild all client-side artifacts (for local dev)
  cd client && yarn run build

client-production-maps: node-deps ## Build optimized artifacts with sourcemaps.
  cd client && yarn run build-production-maps

client-watch: node-deps ## Rebuild client on each change.
  cd client && yarn run watch

client-format: node-deps ## Reformat client code
  cd client && yarn run prettier

client-lint: client-eslint client-format-check ## ES lint and check format of client

client-test: node-deps  ## Run JS unit tests
  cd client && yarn run test

client-test-watch: client ## Watch and run all client unit tests on changes
  cd client && yarn run jest-watch

node-deps: ## Install NodeJS and dependencies.
```

---

### Automatically Reloading During Development

The following command rebuilds the application on each change.

```
make client-watch
```

This is still a relatively slow process, an extra client development server can be started that proxies non-client requests
to your Galaxy server and selectively reloads only what is needed during active development (hot module replacement or HMR).

```
make client-dev-server
```

Make sure to open Galaxy at http://localhost:8081 instead to point at the client proxy.

---

![What is Webpack](../../images/what-is-webpack.svg)

---

### webpack in Galaxy

Packs and "transpiles" Galaxy ES6 code (.js), Galaxy Vue modules (.vue), libraries from npm, scss stylesheets (.scss) into browser native bundles.

Hundreds of high-level well organized files into optimized single files that can be quickly downloaded.

Lots of active development and complexity around Viz plugins and dependencies for instance, but the webpack configuration file in `config/webpack.config.js` is fairly straightforward.

---

![Webpack in Action](../../images/jsload.png)

---

### Stylesheets

- Galaxy shared stylesheets are generally defined using the SCSS syntax
- SCSS is a high-level superset of CSS - https://sass-lang.com/documentation/syntax
- `sass` is leveraged by webpack to convert these styles to native CSS at client build time
- Rebuild style with `make style`
- Galaxy's SCSS files can be found in `client/src/style/scss/`

---

### Package and Build Files

![Client Build Files](../../images/core_files_client_build.mindmap.plantuml.svg)

---

### Source Files

![Client Build Files](../../images/core_files_client_sources.mindmap.plantuml.svg)

---

### ES6

The client is built from JavaScript source files. We use ES6 JavaScript.

A tutorial to help learn JavaScript generally might be https://www.w3schools.com/js/.

For someone familiar with JavaScript but that wants a primer on the new language features in ES6,
https://www.w3schools.com/js/js_es6.asp may be more appropriate.

---

### Vue

Vue.js is a reactive framework for building web client applications.

We chose Vue.js over React initially because of its focus on allowing developers to incrementally or progressively replace pieces of complex existing applications.

The idea behind Vue.js is fairly simple to pick up and there is a lot of great tutorials and videos available. https://vuejs.org/v2/guide/ is a really good jumping off point.

---

### Pinia

> Pinia is a state management library for Vue.js. It provides stores as the central source of truth, with a simpler, more intuitive API compared to earlier solutions. It supports Vue 2 and Vue 3 with Composition API.

https://pinia.vuejs.org/

Key features include devtools integration, hot module replacement, type-safe stores, and seamless TypeScript support.

---

### Client Unit Tests

https://jestjs.io/

Configured in `client/src/jest/jest.config.js`.

Vue tests are placed beside components in `client/src`, more tests in `client/test/qunit/tests` and `client/test/jest/standalone/`.

---

### Vue Test Utils

> Vue Test Utils is the official unit testing utility library for Vue.js.

https://vue-test-utils.vuejs.org/

Really nice reference library documentation. A lot of helpers and concepts to unit test Vue components.

---

### Client Unit Test Design Tips

https://github.com/galaxyproject/galaxy/tree/dev/client/docs/src/component-design/unit-testing

- Clearly document the intent of your test
- Implement logic in pure functions when possible
- Wrap native browser resources in a function so they can be easily mocked

---

### Webhooks in Galaxy

Webhooks is a system in Galaxy which can be used to write small JS and/or Python functions to change predefined locations in the Galaxy client.
<br><br>
In short: A plugin infrastructure for the Galaxy UI

.footnote[You can learn more about webhooks using our webhook [training](/training-material/topics/dev/tutorials/webhooks/slides.html).]

---

### Webhook masthead example

![A person shaped icon in the Galaxy masthead is being hovered over and the popup reads "Show Username", presumably a custom webhook from a tutorial.](../../images/webhook_masthead.png)

At the header menu: Enabling the overlay search, link to communities ...

.footnote[You can learn more about webhooks using our webhook [training](/training-material/topics/dev/tutorials/webhooks/slides.html).]

---

### Webhook tool/workflow example

![Screenshot of Galaxy with the job completion screen shown and a PhD comic image shown below.](../../images/webhook_tool.png)

Shown after tool or workflow execution. Comics, citations, support ...

.footnote[You can learn more about webhooks using our webhook [training](/training-material/topics/dev/tutorials/webhooks/slides.html).]

---

### Webhook history-menu example

![A section of the history menu is labelled Webhooks and shows a custom menu entry.](../../images/webhook_history.png)

Adds an entry to the history menu - no functionality as of now

---

### Galaxy Component Library

Galaxy is replacing Bootstrap-Vue with custom components:

- **Reduce dependency** - Prepare for framework upgrades
- **Improve consistency** - Unified design language
- **Enhance accessibility** - Built-in a11y
- **Simplify maintenance** - Galaxy-specific needs

---

### Deprecated BootstrapVue Components

**Do not use these in new code:**

| BootstrapVue | Use Instead |
|--------------|-------------|
| `BButton`, `b-button` | `GButton` |
| `BLink`, `b-link` | `GLink` |
| `BModal`, `b-modal` | `GModal` |
| `BCard`, `b-card` | `GCard` |

Existing usages should be migrated when touching related code.

---

### Component Migration Effort

**Migration strategy:**

1. **New code** - Always use Galaxy components
2. **Modified code** - Migrate when touching files
3. **Batch migrations** - Periodic focused efforts

Reference PRs:
- [#19963](https://github.com/galaxyproject/galaxy/pull/19963) - Buttons
- [#20063](https://github.com/galaxyproject/galaxy/pull/20063) - Links
- [#20168](https://github.com/galaxyproject/galaxy/pull/20168) - Modal
- [#19785](https://github.com/galaxyproject/galaxy/pull/19785) - Cards

---

### Component Library Patterns

- **Polymorphic** - Same API for button, anchor, router-link
- **Integrated tooltips** - Built-in via `title` + `tooltip` props
- **Semantic colors** - `blue`, `red`, `green` not Bootstrap variants
- **Composable internals** - Shared logic in composables

---

### Creating a Component Wrapper

Follow established patterns:

1. Use `ComponentColor` and `ComponentSize` types
2. Integrate tooltips via `title`/`tooltip` props
3. Use shared composables for common logic
4. Apply CSS custom properties for theming
5. Include ARIA attributes for accessibility

See existing components in `client/src/components/BaseComponents/`

---

### Future Component Work

Likely next components based on Bootstrap-Vue usage:

- **GAlert** - Notification banners
- **GDropdown** - Dropdown menus
- **GTable** - Data tables with sorting
- **GTabs** - Tab navigation
- **GCollapse** - Collapsible sections

.footnote[Previous: [Galaxy Markdown Architecture](/training-material/topics/dev/tutorials/architecture-markdown/slides.html) | Next: [Galaxy Dependencies Management](/training-material/topics/dev/tutorials/architecture-dependencies/slides.html)]

---
### <i class="fas fa-key" aria-hidden="true"></i><span class="visually-hidden">keypoints</span> Key points

- Source in `client/src`, built bundles in `static/dist`

- Webpack handles bundling and transpilation

- Vue.js for reactive components

- ES6 JavaScript

- Jest for unit testing

- Webhooks for UI plugins

---

## Thank You!

This material is the result of a collaborative work. Thanks to the [Galaxy Training Network](https://training.galaxyproject.org) and all the contributors!

</div>

</div>

Tutorial Content is licensed under <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br/>