Skip to content

Improve dashboard layout framework architecture design document based upon finalised approach

Problem to solve

With the creation of the Dashboard Layout Framework architecture design document, we had several areas that we were unsure of until we'd had a chance to implement the framework in code.

Creating the framework as code gives us an opportunity to validate our assumptions, as well as identify any unknowns and document them accordingly.

This issue should be used to update the design document once we have determined the approach we wish to take.

Sections to add

Previous migration strategies content 
We need to consider how to migrate existing dashboard implementations. These dashboards are already solving a need
for users, even if some may have been identified as areas we could improve or provide more value.

We aim in the longer-term for all data-driven dashboards at GitLab to be fully integrated into the dashboard layout
framework. However, this can be a gradual process based upon team capacity and user requirements.
Even more so, as this will require the page to use Vue for rendering, and not every page at GitLab does.

Any migration strategy should have the user requirements, seamless migration, and quality at its heart.

### Replacing everything

In the event that a dashboard isn't meeting our users' needs, or is already scheduled for a revamp, it may be most
prudent to go straight to replacing the existing dashboard with the dashboard layout framework.

This would entail:

- Building visualizations for the data being viewed
- Using the dashboard layout framework to design and build the dashboard
- Adding existing filters or creating new filter types

Oftentimes, dashboards are also migrated to a new location within the navigation at the same time.

The development and swapping over can be managed using feature flags.

### Replacing the dashboard layout

If the visualizations on an existing dashboard are already meeting the needs of users, then it may be expedient
to upgrade the dashboard page itself to make use of the dashboard layout framework.

This would mean keeping the existing visualizations, but integrating them into the wider framework structure.
Therefore, replacing the existing dashboard page layout.

This would entail:

- Replacing the dashboard page layout with the dashboard layout framework
- Replacing the existing dashboard blocks with [panels](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/dashboards-dashboards-panel--docs)
- Rendering the existing visualizations inside [panels](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/dashboards-dashboards-panel--docs)
- Adding existing filters or creating new filters types that can interact with the existing visualizations

### Replacing the panels

If the layout of the dashboard page isn't a concern, then we can keep the existing layout as-is and replace
the dashboard blocks themselves with [panels](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/dashboards-dashboards-panel--docs).

This could also include updating the visualizations at the same time, but it isn't entirely necessary.

This would entail:

- Replacing the existing dashboard blocks with [panels](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/dashboards-dashboards-panel--docs)
- Adding the existing visualizations to panels, or creating new visualizations
- Moving and integrating any existing panel-level filters with the [panels](https://gitlab-org.gitlab.io/gitlab-ui/?path=/docs/dashboards-dashboards-panel--docs)
Edited by Robert Hunt