Documentation

Appearance

Updated Sep 11, 2026 by Barča Dvořáková · Owner: analysisactivefeatureconfluence-migration Edit on GitHub

Dashboard Management ​

Business Context ​

Business-Level Definition ​

The dashboard is a personalisable landing surface for each user. Instead of navigating to individual screens to check recurring information, a user can pin any relevant panel — a chart, a table, a KPI, an external data feed — directly onto their dashboard, and arrange these pinned blocks (tiles) into a layout that suits their workflow.

The core mechanism that makes this new for the product is universal pinning: a "pin to dashboard" action is available from anywhere in the application, not just from a fixed, pre-defined list of dashboard widgets.

Requirements Definition ​

Dashboard management must support:

  • Displaying a grid of tiles, each representing a pinned block of content
  • A reusable pin action that can be attached to any panel in the application (chart, table, KPI, external feed) and captures enough information to reconstruct that panel later
  • Arranging tiles on the grid — moving and resizing, with aspect ratio locked per tile type (resize is allowed along one axis; the other scales proportionally)
  • Persisting each user's tile layout individually (one dashboard per user)
  • Always showing tiles with live data — a tile re-fetches/re-renders current data every time the dashboard loads, not a frozen snapshot from pin time
  • Providing every new user with at least one default tile out of the box (e.g. a weather forecast tile), so the dashboard is never completely empty on first login
  • A lightweight validation mechanism per tile type — each type defines which config keys are required; the pin flow and the render step both check the config against this before accepting/rendering it

Acceptance Criteria ​

  • A user can pin a panel to the dashboard from any screen that has a pin action attached to it
  • A pinned tile is stored as a dashboardBlock (type, grid position, config) belonging to the user's dashboardLayout; config is validated on save against a minimal per-type schema (required keys present) — validation is intentionally primitive in this iteration, but the mechanism (schema registry keyed by type) is in place for future extension
  • Moving or resizing a tile respects the tile's fixed aspect ratio — the user can only scale along one axis, the other axis adjusts automatically
  • A user's dashboard layout is private to that user; there is exactly one dashboard per user
  • On first login, a new user's dashboard is pre-populated with one default tile (weather forecast)
  • Reloading the dashboard always re-renders each tile's live data — no cached/snapshotted content is shown
  • Removing a tile from the dashboard does not delete or affect the underlying source panel — it only removes the pin

N/A — not available in the source material.

Technical Context ​

User Stories / Use Cases ​

Pin a panel to the dashboard: A user is viewing any panel with a pin action available (e.g. a chart, a table) and clicks the pin icon. The panel's current configuration (what it's showing, not a data snapshot) is captured and a new tile is added to the user's dashboard at the next free grid position with the tile type's default size.

View the dashboard: A user opens the dashboard and sees their saved tiles rendered with live data, positioned according to their saved layout. A first-time user sees one default tile (weather forecast).

Rearrange the dashboard: A user drags a tile to a new position on the grid, or resizes it. Resizing preserves the tile type's aspect ratio. The new layout is saved automatically.

Remove a tile: A user removes a tile from the dashboard. The tile disappears from the layout; the source panel elsewhere in the application is unaffected.

UI/UX Design ​

Pending UI/UX review. This first iteration targets a functional proof of concept: the pin mechanism attached to a small number of placeholder tile types, not full visual design across the whole application. Full pin-action rollout to every panel type is follow-up work once the mechanism is proven.

Functional Requirements ​

Tile data model — Conceptually, each tile belongs to exactly one user's dashboard and carries a type, a grid position, and a config whose shape depends on type. See the dashboardLayout and dashboardBlock entity pages (Confluence entity pages, not yet migrated into this repo's Entity DAT catalog) for the authoritative attribute definitions.

Tile type registry and validation — Each type has an associated minimal schema describing its required config keys (e.g. placeholderChart might require title). The pin flow validates a new block's config against this schema before it's accepted; the render step validates it again before drawing the tile. In this iteration, validation only checks required-key presence — no deep type checking — but the mechanism (a type-to-schema registry) is the intended long-term shape, so extending it later doesn't require rearchitecting.

Grid and layout

  • Tiles snap to a fixed grid (grid unit size to be confirmed against the Figma mockup)
  • Each tile type has a default size and a fixed aspect ratio
  • Resize interaction scales one axis; the other axis is derived to preserve aspect ratio
  • Layout (position of every tile) is saved as a whole on every change

Pin action

  • Implemented as a single reusable component that any panel can render (accepting a type and a config as inputs)
  • For this iteration, wired into exactly two places as proof of concept: one placeholder chart panel and one placeholder table panel, both rendering mock data, independent of the Chart Engine
  • Clicking it adds the block to the user's layout at the next free grid position

Default content for new users

  • A new user's dashboard is seeded with exactly one tile: a weather forecast tile (mock data for this iteration; real integration is a later, separate concern)

Persistence

  • FE builds against the documented API contract below. Until the real backend exists, FE mocks the responses matching this contract, so swapping in the real API later requires no FE-side redesign.

Non-Functional Requirements ​

  • Dashboard load must render the saved layout without a visible reflow once tile data arrives — tiles should reserve their grid space immediately based on their position, then fill with data
  • The tile type registry (type-to-schema, type-to-default-size-and-aspect-ratio) should be a single, centrally defined source, not duplicated between the pin flow and the render step

Implementation Notes ​

This iteration deliberately excludes:

  • Real Chart Engine integration — placeholder tile types stand in for real charts
  • Spot price tiles (electricity/gas price feeds) — separate, data-integration-heavy follow-up
  • Multiple dashboards per user, snapshot-mode tiles, admin-configurable default tile sets — none needed for v1

These are called out explicitly so the FE dev doesn't block on them and so reviewers don't mistake the omission for an oversight.

API Analysis ​

Contract to build against — not yet implemented on the backend.

GET   /v1/dashboard    Get current user's dashboard layout (blocks + positions)
PUT   /v1/dashboard    Replace current user's full layout (position changes, add/remove tile)

A single full-layout PUT (rather than per-block CRUD endpoints) matches the "layout is saved as a whole" behaviour above and keeps the contract simple for this iteration.

Domain Model (ER diagram) & Data Attribute Table ​

No ER diagram in source material. Related entity pages (Confluence, not yet migrated into this repo's Entity DAT catalog):

  • dashboardLayout — one dashboard per user
  • dashboardBlock — a single pinned tile (type, grid position, config)

Data ​

New users are seeded with one default dashboardBlock: a weatherForecast tile at a default position with empty config.

Test Data ​

N/A — not covered in source material.

Logging ​

N/A — not covered in source material.

Monitoring ​

N/A — not covered in source material.

Caching ​

N/A — not covered in source material.

Backward Compatibility and Migration ​

No EM2 equivalent exists for the universal pin mechanism — this is new functionality. Dashboard block selection, arrangement and per-user persistence have an EM2 precedent but no migration path is needed since dashboard layout is not historical/reportable data.

N/A — not addressed in the source Confluence page; migrated as a reference copy without new legal analysis.

Cybersecurity Considerations ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new security analysis.

Risk Assessment ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new risk analysis.

Auditing, Reporting & Measurement ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new analysis.

Migrated as a reference copy from Confluence page "Dashboard Management" (id 642711556). Content reorganized to fit this repo's feature-doc template; not re-analyzed against the current codebase.