generated from coulomb/repo-seed
docs: complete personal dashboard framework and implementation plan
Finish IHUB-WP-0020 design work (status finished, all design tasks done) and add IHUB-WP-0021 with the 12-task implementation workplan plus research, PRs, and FDD deliverables produced during the 2026-06-16 review.
This commit is contained in:
609
docs/fdd/personal-dashboard-fdd.md
Normal file
609
docs/fdd/personal-dashboard-fdd.md
Normal file
@@ -0,0 +1,609 @@
|
|||||||
|
# Personal Dashboard Framework FDD
|
||||||
|
|
||||||
|
**Workplan:** IHUB-WP-0020
|
||||||
|
**Date:** 2026-06-16
|
||||||
|
**Status:** Functional design for follow-on implementation workplan
|
||||||
|
**Inputs:** `docs/research/personal-dashboard-current-state.md`,
|
||||||
|
`docs/prs/personal-dashboard-prs.md`
|
||||||
|
|
||||||
|
## 1. Summary
|
||||||
|
|
||||||
|
The personal dashboard is an authenticated, per-user landing surface composed of
|
||||||
|
server-rendered, governed panels. It reuses existing inter-hub data and links to
|
||||||
|
existing source dashboards. It does not replace hub dashboards, governance
|
||||||
|
dashboards, API dashboard, marketplace, or learning dashboard.
|
||||||
|
|
||||||
|
First implementation should ship:
|
||||||
|
|
||||||
|
- one default dashboard per user, with schema ready for multiple dashboards;
|
||||||
|
- six first-slice panel types;
|
||||||
|
- persisted panel layout/config;
|
||||||
|
- stable widget identity for each saved panel;
|
||||||
|
- `widgetEnvelope` wrapping for every rendered panel;
|
||||||
|
- simple server-rendered edit forms;
|
||||||
|
- post-login redirect to the personal dashboard.
|
||||||
|
|
||||||
|
## 2. Design Decisions
|
||||||
|
|
||||||
|
| Topic | Decision |
|
||||||
|
|---|---|
|
||||||
|
| Table prefix | Use `personal_dashboards`, `dashboard_panel_types`, and `dashboard_panels` |
|
||||||
|
| Panel type key field | Use `panel_key`, not `key`, to avoid ambiguous SQL/Haskell naming |
|
||||||
|
| Dashboard multiplicity | Schema supports multiple dashboards; first UI exposes only the default dashboard |
|
||||||
|
| Default dashboard | Created idempotently on first dashboard visit |
|
||||||
|
| Role defaults | No `users.role` column in first slice |
|
||||||
|
| Watched hubs | Represented in panel config for first slice, no separate watched-hub table |
|
||||||
|
| Panel widget ownership | Linked panel widgets are owned by the framework hub |
|
||||||
|
| Panel widget type | Use existing framework-level `panel` widget type |
|
||||||
|
| Panel removal | Soft-remove panel row with `removed_at`; archive linked widget |
|
||||||
|
| Rendering model | Controller/helper builds typed panel view models; views render pure HSX |
|
||||||
|
| Refresh model | Wrap the personal dashboard show action in `autoRefresh` initially |
|
||||||
|
| Client runtime | No JS framework and no client-side data fetch loop |
|
||||||
|
|
||||||
|
## 3. Schema
|
||||||
|
|
||||||
|
### 3.1 Migration Tables
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE personal_dashboards (
|
||||||
|
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
||||||
|
user_id UUID NOT NULL REFERENCES users(id),
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
is_default BOOLEAN NOT NULL DEFAULT FALSE,
|
||||||
|
created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL,
|
||||||
|
updated_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE UNIQUE INDEX personal_dashboards_one_default_idx
|
||||||
|
ON personal_dashboards (user_id)
|
||||||
|
WHERE is_default = TRUE;
|
||||||
|
|
||||||
|
CREATE INDEX personal_dashboards_user_idx
|
||||||
|
ON personal_dashboards (user_id);
|
||||||
|
|
||||||
|
CREATE TABLE dashboard_panel_types (
|
||||||
|
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
||||||
|
panel_key TEXT NOT NULL UNIQUE,
|
||||||
|
label TEXT NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
default_config JSONB NOT NULL DEFAULT '{}',
|
||||||
|
default_col_span INTEGER NOT NULL DEFAULT 4,
|
||||||
|
default_row_span INTEGER NOT NULL DEFAULT 1,
|
||||||
|
live_update BOOLEAN NOT NULL DEFAULT FALSE,
|
||||||
|
status TEXT NOT NULL DEFAULT 'active',
|
||||||
|
created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL,
|
||||||
|
CONSTRAINT dashboard_panel_types_span_check CHECK (
|
||||||
|
default_col_span BETWEEN 1 AND 12
|
||||||
|
AND default_row_span BETWEEN 1 AND 4
|
||||||
|
)
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX dashboard_panel_types_status_idx
|
||||||
|
ON dashboard_panel_types (status);
|
||||||
|
|
||||||
|
CREATE TABLE dashboard_panels (
|
||||||
|
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
||||||
|
dashboard_id UUID NOT NULL REFERENCES personal_dashboards(id) ON DELETE CASCADE,
|
||||||
|
panel_type_id UUID NOT NULL REFERENCES dashboard_panel_types(id),
|
||||||
|
widget_id UUID NOT NULL REFERENCES widgets(id),
|
||||||
|
title TEXT,
|
||||||
|
config JSONB NOT NULL DEFAULT '{}',
|
||||||
|
col INTEGER NOT NULL DEFAULT 0,
|
||||||
|
row INTEGER NOT NULL DEFAULT 0,
|
||||||
|
col_span INTEGER NOT NULL DEFAULT 4,
|
||||||
|
row_span INTEGER NOT NULL DEFAULT 1,
|
||||||
|
sort_order INTEGER NOT NULL DEFAULT 0,
|
||||||
|
created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL,
|
||||||
|
updated_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL,
|
||||||
|
removed_at TIMESTAMP WITH TIME ZONE,
|
||||||
|
CONSTRAINT dashboard_panels_layout_check CHECK (
|
||||||
|
col BETWEEN 0 AND 11
|
||||||
|
AND row >= 0
|
||||||
|
AND col_span BETWEEN 1 AND 12
|
||||||
|
AND row_span BETWEEN 1 AND 4
|
||||||
|
AND col + col_span <= 12
|
||||||
|
)
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX dashboard_panels_dashboard_idx
|
||||||
|
ON dashboard_panels (dashboard_id, removed_at, row, col, sort_order);
|
||||||
|
|
||||||
|
CREATE UNIQUE INDEX dashboard_panels_widget_idx
|
||||||
|
ON dashboard_panels (widget_id);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 Seed Data
|
||||||
|
|
||||||
|
The implementation migration or seed helper must ensure:
|
||||||
|
|
||||||
|
- a framework hub exists with `hub_kind = 'framework'`;
|
||||||
|
- the framework-level `panel` widget type exists and is active;
|
||||||
|
- six `dashboard_panel_types` exist.
|
||||||
|
|
||||||
|
Seed panel types:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
INSERT INTO dashboard_panel_types
|
||||||
|
(panel_key, label, description, default_config, default_col_span,
|
||||||
|
default_row_span, live_update)
|
||||||
|
VALUES
|
||||||
|
('watched-hubs', 'Watched Hubs',
|
||||||
|
'Hub list with latest health hints',
|
||||||
|
'{"limit":12,"displayMode":"compact"}', 6, 1, FALSE),
|
||||||
|
('recent-interactions', 'Recent Activity',
|
||||||
|
'Latest interaction events with widget and hub context',
|
||||||
|
'{"timeRange":"last24h","limit":25,"displayMode":"compact"}', 6, 1, TRUE),
|
||||||
|
('triage-queue', 'Triage Queue',
|
||||||
|
'Open requirement candidates waiting for triage',
|
||||||
|
'{"status":"open","limit":10,"sort":"oldest"}', 6, 1, TRUE),
|
||||||
|
('recent-decisions', 'Recent Decisions',
|
||||||
|
'Recent governance decisions across visible hubs',
|
||||||
|
'{"timeRange":"last30d","limit":10,"sort":"newest"}', 6, 1, FALSE),
|
||||||
|
('hub-health', 'Hub Health',
|
||||||
|
'Latest health snapshots and active bottleneck counts',
|
||||||
|
'{"limit":12,"displayMode":"compact"}', 6, 1, TRUE),
|
||||||
|
('learning-digest', 'Learning Digest',
|
||||||
|
'Recent learning insights and institutional knowledge highlights',
|
||||||
|
'{"insightLimit":5,"knowledgeLimit":5}', 6, 1, TRUE)
|
||||||
|
ON CONFLICT (panel_key) DO NOTHING;
|
||||||
|
```
|
||||||
|
|
||||||
|
The exact framework hub seed should use existing hub invariants and avoid
|
||||||
|
creating a second framework hub. Recommended slug: `inter-hub`.
|
||||||
|
|
||||||
|
## 4. Haskell Types
|
||||||
|
|
||||||
|
### 4.1 Controller Type
|
||||||
|
|
||||||
|
Add to `Web.Types`:
|
||||||
|
|
||||||
|
```haskell
|
||||||
|
data PersonalDashboardsController
|
||||||
|
= PersonalDashboardAction
|
||||||
|
| EditPersonalDashboardAction
|
||||||
|
| UpdatePersonalDashboardAction
|
||||||
|
| AddDashboardPanelAction
|
||||||
|
| UpdateDashboardPanelAction { dashboardPanelId :: !(Id DashboardPanel) }
|
||||||
|
| RemoveDashboardPanelAction { dashboardPanelId :: !(Id DashboardPanel) }
|
||||||
|
deriving (Eq, Show, Data)
|
||||||
|
```
|
||||||
|
|
||||||
|
Register in:
|
||||||
|
|
||||||
|
- `Web/Routes.hs` with `instance AutoRoute PersonalDashboardsController`
|
||||||
|
- `Web/FrontController.hs` imports and controller list
|
||||||
|
- sidebar navigation as `Dashboard`
|
||||||
|
|
||||||
|
### 4.2 Config ADTs
|
||||||
|
|
||||||
|
Store panel config in JSONB. Decode into explicit Haskell types before querying:
|
||||||
|
|
||||||
|
```haskell
|
||||||
|
data TimeRange
|
||||||
|
= Last24Hours
|
||||||
|
| Last7Days
|
||||||
|
| Last30Days
|
||||||
|
| AllTimeBounded
|
||||||
|
deriving (Eq, Show)
|
||||||
|
|
||||||
|
data DisplayMode
|
||||||
|
= Compact
|
||||||
|
| Detailed
|
||||||
|
deriving (Eq, Show)
|
||||||
|
|
||||||
|
data SortMode
|
||||||
|
= Newest
|
||||||
|
| Oldest
|
||||||
|
| HighestRisk
|
||||||
|
deriving (Eq, Show)
|
||||||
|
|
||||||
|
data DashboardPanelConfig
|
||||||
|
= WatchedHubsConfig
|
||||||
|
{ hubIds :: !(Maybe [Id Hub])
|
||||||
|
, limit :: !Int
|
||||||
|
, displayMode :: !DisplayMode
|
||||||
|
}
|
||||||
|
| RecentInteractionsConfig
|
||||||
|
{ hubIds :: !(Maybe [Id Hub])
|
||||||
|
, timeRange :: !TimeRange
|
||||||
|
, limit :: !Int
|
||||||
|
, displayMode :: !DisplayMode
|
||||||
|
}
|
||||||
|
| TriageQueueConfig
|
||||||
|
{ hubIds :: !(Maybe [Id Hub])
|
||||||
|
, status :: !Text
|
||||||
|
, limit :: !Int
|
||||||
|
, sortMode :: !SortMode
|
||||||
|
}
|
||||||
|
| RecentDecisionsConfig
|
||||||
|
{ hubIds :: !(Maybe [Id Hub])
|
||||||
|
, timeRange :: !TimeRange
|
||||||
|
, limit :: !Int
|
||||||
|
, sortMode :: !SortMode
|
||||||
|
}
|
||||||
|
| HubHealthConfig
|
||||||
|
{ hubIds :: !(Maybe [Id Hub])
|
||||||
|
, limit :: !Int
|
||||||
|
, displayMode :: !DisplayMode
|
||||||
|
}
|
||||||
|
| LearningDigestConfig
|
||||||
|
{ hubIds :: !(Maybe [Id Hub])
|
||||||
|
, insightLimit :: !Int
|
||||||
|
, knowledgeLimit :: !Int
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Implementation can place these in `Application/Helper/PersonalDashboard.hs`.
|
||||||
|
Config decoding should return warnings instead of crashing:
|
||||||
|
|
||||||
|
```haskell
|
||||||
|
data PanelConfigResult
|
||||||
|
= PanelConfigOk DashboardPanelConfig
|
||||||
|
| PanelConfigWithWarnings DashboardPanelConfig [Text]
|
||||||
|
```
|
||||||
|
|
||||||
|
Clamp all limits server-side. Recommended default min/max:
|
||||||
|
|
||||||
|
- list panel limit: 1 to 50;
|
||||||
|
- hub list limit: 1 to 50;
|
||||||
|
- learning insight/knowledge limits: 1 to 20;
|
||||||
|
- column span: 1 to 12;
|
||||||
|
- row span: 1 to 4.
|
||||||
|
|
||||||
|
### 4.3 View Model ADT
|
||||||
|
|
||||||
|
Do not query from HSX views. Build typed view models in the controller/helper:
|
||||||
|
|
||||||
|
```haskell
|
||||||
|
data PersonalDashboardViewModel = PersonalDashboardViewModel
|
||||||
|
{ dashboard :: !PersonalDashboard
|
||||||
|
, panels :: ![DashboardPanelViewModel]
|
||||||
|
, panelTypes :: ![DashboardPanelType]
|
||||||
|
}
|
||||||
|
|
||||||
|
data DashboardPanelViewModel
|
||||||
|
= WatchedHubsPanel DashboardPanel Widget [WatchedHubRow] [Text]
|
||||||
|
| RecentInteractionsPanel DashboardPanel Widget [RecentInteractionRow] [Text]
|
||||||
|
| TriageQueuePanel DashboardPanel Widget [TriageQueueRow] [Text]
|
||||||
|
| RecentDecisionsPanel DashboardPanel Widget [RecentDecisionRow] [Text]
|
||||||
|
| HubHealthPanel DashboardPanel Widget [HubHealthRow] [Text]
|
||||||
|
| LearningDigestPanel DashboardPanel Widget [LearningDigestRow] [Text]
|
||||||
|
| UnsupportedPanel DashboardPanel Widget Text [Text]
|
||||||
|
```
|
||||||
|
|
||||||
|
Each row type should carry exactly the fields the view needs, plus source route
|
||||||
|
ids for link-outs.
|
||||||
|
|
||||||
|
## 5. Controller Flow
|
||||||
|
|
||||||
|
### 5.1 Show
|
||||||
|
|
||||||
|
```text
|
||||||
|
GET /PersonalDashboard
|
||||||
|
-> ensureIsUser
|
||||||
|
-> ensureDefaultDashboard currentUser
|
||||||
|
-> fetch active dashboard panels ordered by row, col, sort_order
|
||||||
|
-> build DashboardPanelViewModel for each panel
|
||||||
|
-> render ShowView
|
||||||
|
```
|
||||||
|
|
||||||
|
The first implementation may wrap `PersonalDashboardAction` in `autoRefresh do`.
|
||||||
|
|
||||||
|
### 5.2 Edit
|
||||||
|
|
||||||
|
```text
|
||||||
|
GET /PersonalDashboard/Edit
|
||||||
|
-> ensureIsUser
|
||||||
|
-> ensureDefaultDashboard currentUser
|
||||||
|
-> fetch active panels and active panel types
|
||||||
|
-> render EditView
|
||||||
|
```
|
||||||
|
|
||||||
|
Edit view should show:
|
||||||
|
|
||||||
|
- panel title;
|
||||||
|
- panel type label;
|
||||||
|
- row, col, col span, row span;
|
||||||
|
- limit/time range/hub filter where supported;
|
||||||
|
- remove button;
|
||||||
|
- add panel form.
|
||||||
|
|
||||||
|
### 5.3 Update Layout/Config
|
||||||
|
|
||||||
|
`UpdatePersonalDashboardAction` should accept a simple form payload for all
|
||||||
|
active panels. It should:
|
||||||
|
|
||||||
|
- authorize that the dashboard belongs to current user;
|
||||||
|
- validate layout bounds;
|
||||||
|
- validate per-panel config;
|
||||||
|
- update dashboard/panel `updated_at`;
|
||||||
|
- redirect back to edit or show with success/error messages.
|
||||||
|
|
||||||
|
### 5.4 Add Panel
|
||||||
|
|
||||||
|
`AddDashboardPanelAction` should:
|
||||||
|
|
||||||
|
1. fetch current user's default dashboard;
|
||||||
|
2. fetch selected active `DashboardPanelType`;
|
||||||
|
3. find/create the framework hub;
|
||||||
|
4. create linked `Widget`;
|
||||||
|
5. create initial `WidgetVersion`;
|
||||||
|
6. create `DashboardPanel` with default config and next layout slot;
|
||||||
|
7. redirect to edit.
|
||||||
|
|
||||||
|
### 5.5 Remove Panel
|
||||||
|
|
||||||
|
`RemoveDashboardPanelAction { dashboardPanelId }` should:
|
||||||
|
|
||||||
|
1. verify the panel belongs to current user's dashboard;
|
||||||
|
2. set `dashboard_panels.removed_at`;
|
||||||
|
3. set linked widget `is_archived = TRUE` and `status = 'deprecated'`;
|
||||||
|
4. keep interaction events and annotations intact;
|
||||||
|
5. redirect to edit.
|
||||||
|
|
||||||
|
## 6. Default Dashboard Seeding
|
||||||
|
|
||||||
|
Recommended helper:
|
||||||
|
|
||||||
|
```haskell
|
||||||
|
ensureDefaultDashboard :: (?modelContext :: ModelContext) => User -> IO PersonalDashboard
|
||||||
|
```
|
||||||
|
|
||||||
|
Behavior:
|
||||||
|
|
||||||
|
1. Query default dashboard for user.
|
||||||
|
2. If found, return it.
|
||||||
|
3. If absent, create `personal_dashboards` row with name `My Dashboard`.
|
||||||
|
4. Fetch active first-slice `DashboardPanelType` rows.
|
||||||
|
5. Create one linked widget and one panel row for each seed panel.
|
||||||
|
6. Return the dashboard.
|
||||||
|
|
||||||
|
Default layout:
|
||||||
|
|
||||||
|
| Panel | col | row | col_span | row_span |
|
||||||
|
|---|---:|---:|---:|---:|
|
||||||
|
| watched-hubs | 0 | 0 | 6 | 1 |
|
||||||
|
| recent-interactions | 6 | 0 | 6 | 1 |
|
||||||
|
| triage-queue | 0 | 1 | 6 | 1 |
|
||||||
|
| recent-decisions | 6 | 1 | 6 | 1 |
|
||||||
|
| hub-health | 0 | 2 | 6 | 1 |
|
||||||
|
| learning-digest | 6 | 2 | 6 | 1 |
|
||||||
|
|
||||||
|
If a user has active stewardship roles matched by email or name, panel config
|
||||||
|
may include those hub ids. If no match exists, config should stay neutral.
|
||||||
|
|
||||||
|
## 7. Panel Renderer Query Shapes
|
||||||
|
|
||||||
|
All panel queries must be bounded and must not expose secrets.
|
||||||
|
|
||||||
|
### Watched Hubs
|
||||||
|
|
||||||
|
Purpose: show hub names, domains/kinds, latest health score if available, and a
|
||||||
|
link to `ShowHubAction`.
|
||||||
|
|
||||||
|
Query shape:
|
||||||
|
|
||||||
|
- fetch hubs matching optional hub filter, order by name, limit N;
|
||||||
|
- fetch latest health snapshots for those hub ids using `DISTINCT ON (hub_id)`
|
||||||
|
or equivalent bounded query.
|
||||||
|
|
||||||
|
### Recent Activity
|
||||||
|
|
||||||
|
Purpose: show recent interaction events with widget and hub context.
|
||||||
|
|
||||||
|
Query shape:
|
||||||
|
|
||||||
|
- filter by optional hub ids through widget join;
|
||||||
|
- filter by time range;
|
||||||
|
- order by `interaction_events.occurred_at DESC`;
|
||||||
|
- limit N;
|
||||||
|
- fetch widget/hub names for display.
|
||||||
|
|
||||||
|
### Triage Queue
|
||||||
|
|
||||||
|
Purpose: show open requirement candidates that need attention.
|
||||||
|
|
||||||
|
Query shape:
|
||||||
|
|
||||||
|
- filter `requirement_candidates.status = 'open'`;
|
||||||
|
- optionally filter by source widget hub;
|
||||||
|
- order oldest first by default;
|
||||||
|
- limit N;
|
||||||
|
- fetch source widget and hub names.
|
||||||
|
|
||||||
|
### Recent Decisions
|
||||||
|
|
||||||
|
Purpose: show governance decisions that changed recently.
|
||||||
|
|
||||||
|
Query shape:
|
||||||
|
|
||||||
|
- filter by time range on `decided_at` or `created_at` fallback;
|
||||||
|
- optionally filter by hub through requirement candidate source widget lineage;
|
||||||
|
- order newest first;
|
||||||
|
- limit N.
|
||||||
|
|
||||||
|
### Hub Health
|
||||||
|
|
||||||
|
Purpose: show latest health score and active bottleneck count.
|
||||||
|
|
||||||
|
Query shape:
|
||||||
|
|
||||||
|
- latest `hub_health_snapshots` per hub;
|
||||||
|
- active `bottleneck_records` count per hub;
|
||||||
|
- limit N hubs by health score ascending or hub name depending config.
|
||||||
|
|
||||||
|
When decoding aggregate counts as `Int`, cast `COUNT(*) AS integer` or decode
|
||||||
|
as `Int64`.
|
||||||
|
|
||||||
|
### Learning Digest
|
||||||
|
|
||||||
|
Purpose: show recent `learning_insights` and
|
||||||
|
`institutional_knowledge_entries`.
|
||||||
|
|
||||||
|
Query shape:
|
||||||
|
|
||||||
|
- optional hub filter;
|
||||||
|
- latest insights ordered by `computed_at DESC`, limit N;
|
||||||
|
- latest knowledge entries ordered by `created_at DESC`, limit N;
|
||||||
|
- link to source knowledge entries when available.
|
||||||
|
|
||||||
|
## 8. Layout
|
||||||
|
|
||||||
|
Desktop layout:
|
||||||
|
|
||||||
|
- 12-column CSS grid.
|
||||||
|
- panel spans come from `dashboard_panels.col_span` and `row_span`.
|
||||||
|
- layout ordering comes from row, col, sort order.
|
||||||
|
- gap should match existing dashboard spacing.
|
||||||
|
|
||||||
|
Mobile/narrow layout:
|
||||||
|
|
||||||
|
- collapse to a single column.
|
||||||
|
- ignore column positions visually.
|
||||||
|
- preserve row/sort ordering.
|
||||||
|
|
||||||
|
Implementation approach:
|
||||||
|
|
||||||
|
- add a small CSS helper in `static/app.css` if inline styles cannot express the
|
||||||
|
responsive collapse cleanly;
|
||||||
|
- keep panel headings at compact dashboard scale;
|
||||||
|
- avoid nested cards;
|
||||||
|
- keep source link and annotate control visible but quiet.
|
||||||
|
|
||||||
|
## 9. Routing and Navigation
|
||||||
|
|
||||||
|
Add:
|
||||||
|
|
||||||
|
- `PersonalDashboardAction`
|
||||||
|
- `EditPersonalDashboardAction`
|
||||||
|
- `UpdatePersonalDashboardAction`
|
||||||
|
- `AddDashboardPanelAction`
|
||||||
|
- `UpdateDashboardPanelAction`
|
||||||
|
- `RemoveDashboardPanelAction`
|
||||||
|
|
||||||
|
Expected user-facing routes with AutoRoute naming are acceptable. If a cleaner
|
||||||
|
path is desired, add explicit `HasPath`/`CanRoute` later. First implementation
|
||||||
|
can use AutoRoute for speed and consistency.
|
||||||
|
|
||||||
|
Update login:
|
||||||
|
|
||||||
|
```haskell
|
||||||
|
login user
|
||||||
|
redirectTo PersonalDashboardAction
|
||||||
|
```
|
||||||
|
|
||||||
|
Do not alter:
|
||||||
|
|
||||||
|
- public `LandingAction`;
|
||||||
|
- docs/tutorial/extension guide routes;
|
||||||
|
- existing `HubsAction` route.
|
||||||
|
|
||||||
|
## 10. Governance Lifecycle
|
||||||
|
|
||||||
|
### Panel Add
|
||||||
|
|
||||||
|
- create `DashboardPanel`;
|
||||||
|
- create linked `Widget`;
|
||||||
|
- create initial `WidgetVersion` snapshot with panel type and config;
|
||||||
|
- render through `widgetEnvelope`.
|
||||||
|
|
||||||
|
### Panel Update
|
||||||
|
|
||||||
|
- update `DashboardPanel.config` and layout fields;
|
||||||
|
- update panel widget name/view context only if needed;
|
||||||
|
- create a new `WidgetVersion` snapshot when config changes materially.
|
||||||
|
|
||||||
|
### Panel Remove
|
||||||
|
|
||||||
|
- set `dashboard_panels.removed_at`;
|
||||||
|
- set widget `is_archived = TRUE`;
|
||||||
|
- set widget `status = 'deprecated'`;
|
||||||
|
- preserve events and annotations.
|
||||||
|
|
||||||
|
### Annotation
|
||||||
|
|
||||||
|
The existing `WidgetAnnotationsAction` should work because panels have stable
|
||||||
|
widget ids.
|
||||||
|
|
||||||
|
### Event Capture
|
||||||
|
|
||||||
|
Existing client-side capture can identify panels via `data-widget-id`. If panel
|
||||||
|
forms submit through normal controller actions, use existing event types where
|
||||||
|
possible (`viewed`, `clicked`, `submitted`, `commented`).
|
||||||
|
|
||||||
|
## 11. Error Handling
|
||||||
|
|
||||||
|
- Missing dashboard: create default.
|
||||||
|
- Missing panel type: render `UnsupportedPanel` with warning.
|
||||||
|
- Invalid config: use defaults and render warning.
|
||||||
|
- Missing linked widget: repair by creating a replacement widget if possible,
|
||||||
|
otherwise render unsupported warning.
|
||||||
|
- Missing framework hub: create the framework hub if absent, honoring unique
|
||||||
|
framework hub constraint.
|
||||||
|
- Empty panel data: render a quiet empty state.
|
||||||
|
|
||||||
|
## 12. Tests and Smoke Checks
|
||||||
|
|
||||||
|
Focused automated checks:
|
||||||
|
|
||||||
|
- `ensureDefaultDashboard` is idempotent.
|
||||||
|
- seeded dashboard contains six active panels.
|
||||||
|
- each seeded panel has a linked widget.
|
||||||
|
- config decoder clamps limits and rejects unknown values safely.
|
||||||
|
- unauthorized user cannot edit another user's dashboard.
|
||||||
|
- remove action soft-removes panel and archives widget.
|
||||||
|
|
||||||
|
Manual smoke:
|
||||||
|
|
||||||
|
1. Log in as the seeded admin user.
|
||||||
|
2. Confirm redirect lands on personal dashboard.
|
||||||
|
3. Confirm all six seeded panels render.
|
||||||
|
4. Click source links from at least three panels.
|
||||||
|
5. Open Annotate for one panel and confirm existing annotation flow loads.
|
||||||
|
6. Edit layout, save, sign out/in, and confirm layout persists.
|
||||||
|
7. Add a panel and remove a panel.
|
||||||
|
8. Confirm `HubsAction`, hub show, Ops Review, Learning, API Dashboard, and
|
||||||
|
Marketplace still load.
|
||||||
|
|
||||||
|
## 13. Implementation File Map
|
||||||
|
|
||||||
|
Expected files for WP-0021:
|
||||||
|
|
||||||
|
- `Application/Migration/<timestamp>-personal-dashboard-framework.sql`
|
||||||
|
- `Application/Helper/PersonalDashboard.hs`
|
||||||
|
- `Web/Controller/PersonalDashboards.hs`
|
||||||
|
- `Web/View/PersonalDashboards/Show.hs`
|
||||||
|
- `Web/View/PersonalDashboards/Edit.hs`
|
||||||
|
- `Web/Types.hs`
|
||||||
|
- `Web/Routes.hs`
|
||||||
|
- `Web/FrontController.hs`
|
||||||
|
- `static/app.css` only if needed for responsive grid helpers
|
||||||
|
- focused tests under `Test/` if the current test harness supports controller or
|
||||||
|
helper tests
|
||||||
|
|
||||||
|
## 14. Open Questions
|
||||||
|
|
||||||
|
These do not block WP-0021, but should be revisited after the first
|
||||||
|
implementation:
|
||||||
|
|
||||||
|
1. Should personal dashboards later support team/shared dashboards?
|
||||||
|
2. Should watched hubs become a first-class table after users start editing
|
||||||
|
dashboards?
|
||||||
|
3. Should per-panel refresh be extracted into fragment routes?
|
||||||
|
4. Should dashboard panel widgets eventually be owned by source hubs instead of
|
||||||
|
the framework hub?
|
||||||
|
5. Should dashboard templates become part of the marketplace?
|
||||||
|
|
||||||
|
## 15. Handoff to WP-0021
|
||||||
|
|
||||||
|
WP-0021 should implement this design in small slices:
|
||||||
|
|
||||||
|
1. schema and seeds;
|
||||||
|
2. controller/route skeleton and default seeding;
|
||||||
|
3. first three panel view models/renderers;
|
||||||
|
4. dashboard show view;
|
||||||
|
5. remaining panel view models/renderers;
|
||||||
|
6. edit flow;
|
||||||
|
7. governance lifecycle;
|
||||||
|
8. login redirect and navigation;
|
||||||
|
9. tests and smoke.
|
||||||
340
docs/prs/personal-dashboard-prs.md
Normal file
340
docs/prs/personal-dashboard-prs.md
Normal file
@@ -0,0 +1,340 @@
|
|||||||
|
# Personal Dashboard Framework PRS
|
||||||
|
|
||||||
|
**Workplan:** IHUB-WP-0020
|
||||||
|
**Date:** 2026-06-16
|
||||||
|
**Status:** Product requirements for follow-on FDD and implementation planning
|
||||||
|
**Research input:** `docs/research/personal-dashboard-current-state.md`
|
||||||
|
|
||||||
|
## 1. Problem Statement
|
||||||
|
|
||||||
|
Authenticated inter-hub users currently land on the Hubs list after login. That
|
||||||
|
list is a useful management table, but it does not answer the daily operating
|
||||||
|
questions users bring to inter-hub:
|
||||||
|
|
||||||
|
- What changed recently?
|
||||||
|
- Which candidates or governance items need attention?
|
||||||
|
- Which hubs are unhealthy or blocked?
|
||||||
|
- Which learning or institutional knowledge signals should I notice today?
|
||||||
|
- Where should I go next?
|
||||||
|
|
||||||
|
Inter-hub already has many specialized dashboards, but they are scattered across
|
||||||
|
hub-level and platform-level routes. Users must know which surface to visit and
|
||||||
|
manually stitch together recent activity, open work, health, governance, and
|
||||||
|
learning signals.
|
||||||
|
|
||||||
|
The personal dashboard should become the authenticated landing surface that
|
||||||
|
summarizes the most relevant existing signals and links users to the source
|
||||||
|
dashboards for detail. It should be persistent, configurable, server-rendered,
|
||||||
|
and governed by the same IHF widget, annotation, and interaction-event model as
|
||||||
|
the rest of the application.
|
||||||
|
|
||||||
|
## 2. Users and Personas
|
||||||
|
|
||||||
|
### Hub Operator
|
||||||
|
|
||||||
|
Owns or watches one or more hubs. Needs quick visibility into recent events,
|
||||||
|
open requirement candidates, hub health, active bottlenecks, and regressions.
|
||||||
|
|
||||||
|
Primary questions:
|
||||||
|
|
||||||
|
- Which hubs need attention now?
|
||||||
|
- What happened since the last session?
|
||||||
|
- Which candidates are still open?
|
||||||
|
- Are any bottlenecks or health drops visible?
|
||||||
|
|
||||||
|
### Governance Reviewer
|
||||||
|
|
||||||
|
Triages candidates, reviews decisions, checks policy coverage, and follows
|
||||||
|
traceability from observations to implementation outcomes.
|
||||||
|
|
||||||
|
Primary questions:
|
||||||
|
|
||||||
|
- Which candidates are waiting for triage?
|
||||||
|
- Which decisions or requirements changed recently?
|
||||||
|
- Which panels need annotation or review?
|
||||||
|
- Are governance signals visible without visiting every hub?
|
||||||
|
|
||||||
|
### AI Orchestrator
|
||||||
|
|
||||||
|
Monitors agent proposals, review outcomes, learning signals, and institutional
|
||||||
|
knowledge that may affect future AI-assisted work.
|
||||||
|
|
||||||
|
Primary questions:
|
||||||
|
|
||||||
|
- Which agent proposals or reviews need attention?
|
||||||
|
- What learning insights were generated recently?
|
||||||
|
- Which knowledge entries should inform the next work session?
|
||||||
|
- Are there patterns of repeated friction or successful reuse?
|
||||||
|
|
||||||
|
### Platform Admin
|
||||||
|
|
||||||
|
Watches the inter-hub platform itself: API consumers, hub registry health,
|
||||||
|
manifests, policy overlays, marketplace activity, and cross-hub propagation.
|
||||||
|
|
||||||
|
Primary questions:
|
||||||
|
|
||||||
|
- Are API consumers active and healthy?
|
||||||
|
- Are hub manifests and registry views coherent?
|
||||||
|
- Are cross-hub governance or propagation signals emerging?
|
||||||
|
- Which operational panels should be promoted into a shared view later?
|
||||||
|
|
||||||
|
## 3. Product Goals
|
||||||
|
|
||||||
|
- Replace the authenticated post-login Hubs table as the daily landing surface.
|
||||||
|
- Provide a compact, configurable overview of existing inter-hub signals.
|
||||||
|
- Preserve the existing specialized dashboards as source-of-truth detail views.
|
||||||
|
- Make every saved panel a governed IHF interaction artifact.
|
||||||
|
- Keep the first implementation simple enough to deliver without a broad
|
||||||
|
dashboard refactor.
|
||||||
|
|
||||||
|
## 4. Non-Goals
|
||||||
|
|
||||||
|
- Do not build a drag-and-drop report builder.
|
||||||
|
- Do not add external datasource connectors.
|
||||||
|
- Do not introduce a client-side data fetching framework.
|
||||||
|
- Do not refactor all existing dashboards into reusable panel modules in the
|
||||||
|
first slice.
|
||||||
|
- Do not add a full role/permission system.
|
||||||
|
- Do not make shared/team dashboards part of the first implementation.
|
||||||
|
- Do not change public root, tutorial, capabilities, or extension-guide routes.
|
||||||
|
|
||||||
|
## 5. Core Requirements
|
||||||
|
|
||||||
|
### Must
|
||||||
|
|
||||||
|
- Provide an authenticated personal dashboard route.
|
||||||
|
- Redirect successful login to the personal dashboard instead of `HubsAction`.
|
||||||
|
- Preserve public root behavior for unauthenticated and documentation users.
|
||||||
|
- Persist at least one dashboard per user.
|
||||||
|
- Seed a default dashboard on first visit.
|
||||||
|
- Persist panel instances, layout position, and panel config.
|
||||||
|
- Render all first-slice panels server-side through IHP/HSX.
|
||||||
|
- Use a server-side panel catalogue with stable panel keys.
|
||||||
|
- Bound every panel query by limit and, where relevant, hub/status/time filters.
|
||||||
|
- Decode JSONB panel config into explicit Haskell config types before querying.
|
||||||
|
- Create or reference stable `Widget` records for saved panel instances.
|
||||||
|
- Wrap rendered panels with `widgetEnvelope`.
|
||||||
|
- Preserve annotation and interaction-event identity across sessions.
|
||||||
|
- Link each panel to its existing source dashboard or source entity list.
|
||||||
|
- Provide a simple edit mode for adding, removing, and reordering panels through
|
||||||
|
normal IHP forms.
|
||||||
|
|
||||||
|
### Should
|
||||||
|
|
||||||
|
- Support hub filters for panels backed by hub-owned data.
|
||||||
|
- Support simple time-range filters where the underlying table has timestamps.
|
||||||
|
- Support limit/display-mode settings for panels with list content.
|
||||||
|
- Refresh recent activity, triage, health, and learning panels using the
|
||||||
|
existing `autoRefresh` style.
|
||||||
|
- Keep forms keyboard accessible and understandable without custom JavaScript.
|
||||||
|
- Render a neutral empty state when a panel has no data.
|
||||||
|
- Provide safe fallback behavior for invalid panel config.
|
||||||
|
- Keep first paint sub-second for a seeded dashboard with default panels.
|
||||||
|
- Use existing Tailwind/card/table visual conventions.
|
||||||
|
|
||||||
|
### Could
|
||||||
|
|
||||||
|
- Add saved watched-hub sets.
|
||||||
|
- Add multiple named dashboards per user.
|
||||||
|
- Add dashboard templates.
|
||||||
|
- Add shared/team dashboards.
|
||||||
|
- Add more panel types after the first framework slice is proven.
|
||||||
|
- Add finer-grained panel refresh routes later.
|
||||||
|
- Add user-selected default landing dashboard later.
|
||||||
|
|
||||||
|
### Won't for First Implementation
|
||||||
|
|
||||||
|
- Drag-and-drop layout editing.
|
||||||
|
- Mobile-native layout editor.
|
||||||
|
- Client-side data fetching.
|
||||||
|
- External dashboard or BI embedding.
|
||||||
|
- External datasource credentials.
|
||||||
|
- Role-based access control beyond existing authenticated controller guards.
|
||||||
|
- Complex visual charting library integration.
|
||||||
|
|
||||||
|
## 6. First-Slice Panel Catalogue
|
||||||
|
|
||||||
|
The first implementation should prove the framework with a small panel set.
|
||||||
|
|
||||||
|
| Panel key | Label | Purpose | Default behavior |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `watched-hubs` | Watched Hubs | Show hub list plus latest health hint | All hubs, limit 12 |
|
||||||
|
| `recent-interactions` | Recent Activity | Show latest interaction events with hub/widget context | Last 24h, limit 25 |
|
||||||
|
| `triage-queue` | Triage Queue | Show open requirement candidates | Open status, oldest first, limit 10 |
|
||||||
|
| `recent-decisions` | Recent Decisions | Show recent governance decisions | Last 30 days, newest first, limit 10 |
|
||||||
|
| `hub-health` | Hub Health | Show latest health snapshot and active blockers | Latest per hub, limit 12 |
|
||||||
|
| `learning-digest` | Learning Digest | Show latest insights and knowledge highlights | Latest insights and entries, limit 5 each |
|
||||||
|
|
||||||
|
Deferred panel catalogue candidates:
|
||||||
|
|
||||||
|
- `agent-proposals`
|
||||||
|
- `api-usage`
|
||||||
|
- `marketplace-trending`
|
||||||
|
- `my-annotations`
|
||||||
|
- `policy-compliance`
|
||||||
|
- `adapter-compatibility`
|
||||||
|
- `cross-hub-propagations`
|
||||||
|
|
||||||
|
## 7. Functional Requirements
|
||||||
|
|
||||||
|
### Dashboard Route
|
||||||
|
|
||||||
|
- Add a `PersonalDashboardsController` or similarly named controller.
|
||||||
|
- Add a show action for the current user's default dashboard.
|
||||||
|
- Add edit/update/add/remove actions for panel management.
|
||||||
|
- Register routes in `Web.Routes` and `Web.FrontController`.
|
||||||
|
- Add a sidebar link labelled `Dashboard`.
|
||||||
|
|
||||||
|
### Dashboard Persistence
|
||||||
|
|
||||||
|
- Store dashboard ownership by `users.id`.
|
||||||
|
- Support at least one default dashboard per user.
|
||||||
|
- Store panel order and grid layout.
|
||||||
|
- Store panel config in JSONB.
|
||||||
|
- Store a linked panel widget id for governance.
|
||||||
|
- Keep panel deletion non-destructive with respect to historical events and
|
||||||
|
annotations.
|
||||||
|
|
||||||
|
### Default Seeding
|
||||||
|
|
||||||
|
- On first visit, create a default dashboard for the authenticated user.
|
||||||
|
- Seed the first-slice panels with safe default config.
|
||||||
|
- Do not require a `users.role` column.
|
||||||
|
- Best-effort hub relevance may use active `stewardship_roles.assigned_to`
|
||||||
|
matching user email or name, but the neutral default must work without it.
|
||||||
|
|
||||||
|
### Panel Rendering
|
||||||
|
|
||||||
|
- Dispatch panels by stable catalogue key.
|
||||||
|
- Decode and validate config before querying.
|
||||||
|
- Use bounded queries.
|
||||||
|
- Render empty states and config warnings without crashing the whole dashboard.
|
||||||
|
- Wrap every rendered panel in `widgetEnvelope`.
|
||||||
|
- Link to source dashboards for deeper work.
|
||||||
|
|
||||||
|
### Edit Mode
|
||||||
|
|
||||||
|
- List current panels in layout order.
|
||||||
|
- Allow adding a panel from active panel types.
|
||||||
|
- Allow removing a panel from the dashboard.
|
||||||
|
- Allow editing column, row, span, limit, hub filter, time range, and display
|
||||||
|
mode where supported.
|
||||||
|
- Validate layout spans and config values server-side.
|
||||||
|
- Keep forms usable without custom JavaScript.
|
||||||
|
|
||||||
|
### Governance and Event Capture
|
||||||
|
|
||||||
|
- Saved panels must use stable `Widget` rows.
|
||||||
|
- Panel widgets should use the existing `panel` widget type.
|
||||||
|
- Panel widget `view_context` must be non-empty.
|
||||||
|
- Panel annotations must attach to the panel widget id.
|
||||||
|
- Panel interaction capture should use existing event types where possible.
|
||||||
|
- Adding/removing/reconfiguring panels should not mutate historical
|
||||||
|
interaction events.
|
||||||
|
|
||||||
|
## 8. Non-Functional Requirements
|
||||||
|
|
||||||
|
### Performance
|
||||||
|
|
||||||
|
- Default dashboard first paint target: under 1 second in local development
|
||||||
|
with seeded fixtures.
|
||||||
|
- Each panel query should have a default row limit.
|
||||||
|
- Any aggregate query decoded as `Int` must cast `COUNT(*)` to integer or
|
||||||
|
decode as `Int64`.
|
||||||
|
- Avoid N+1 patterns where a simple join or batched fetch is practical.
|
||||||
|
- Use existing indexes where available; document new index needs in the FDD.
|
||||||
|
|
||||||
|
### Reliability
|
||||||
|
|
||||||
|
- Invalid panel config should not break the whole dashboard.
|
||||||
|
- Missing source data should render an empty state.
|
||||||
|
- Missing linked widget should be repaired or reported by the controller before
|
||||||
|
rendering.
|
||||||
|
- Dashboard seeding should be idempotent.
|
||||||
|
- Login redirect should fall back gracefully if dashboard seeding fails.
|
||||||
|
|
||||||
|
### Security and Privacy
|
||||||
|
|
||||||
|
- Dashboard routes require authenticated users.
|
||||||
|
- Users can view and edit only their own personal dashboard in the first slice.
|
||||||
|
- No secrets, API keys, or token values may be shown in dashboard panels.
|
||||||
|
- API usage panels must show only non-secret consumer metadata.
|
||||||
|
- Panel config must not become an arbitrary SQL or route execution surface.
|
||||||
|
|
||||||
|
### Accessibility and Usability
|
||||||
|
|
||||||
|
- Use semantic headings for panels.
|
||||||
|
- Use tables/lists for scan-heavy operational data.
|
||||||
|
- Use form labels for all edit inputs.
|
||||||
|
- Keep navigation links clear and predictable.
|
||||||
|
- Do not rely on hover-only controls for essential edits.
|
||||||
|
|
||||||
|
### Maintainability
|
||||||
|
|
||||||
|
- Put renderer dispatch and config decoding in a focused helper/module.
|
||||||
|
- Keep panel renderer functions small and testable.
|
||||||
|
- Avoid moving existing dashboard code unless required.
|
||||||
|
- Prefer additive schema migrations.
|
||||||
|
- Keep first implementation tasks small enough for separate Codex sessions.
|
||||||
|
|
||||||
|
## 9. Acceptance Criteria
|
||||||
|
|
||||||
|
The product design is acceptable when the FDD can specify:
|
||||||
|
|
||||||
|
- Exact schema tables and fields.
|
||||||
|
- Exact controller/action names.
|
||||||
|
- Exact default panel seed set.
|
||||||
|
- Exact panel config types and defaults.
|
||||||
|
- Exact first-slice panel query shapes.
|
||||||
|
- Exact governance identity lifecycle for panel widgets.
|
||||||
|
- Exact smoke tests for login, dashboard seeding, editing, annotation, and
|
||||||
|
source dashboard link-outs.
|
||||||
|
|
||||||
|
The implementation will be acceptable when:
|
||||||
|
|
||||||
|
- A new authenticated user lands on a seeded personal dashboard after login.
|
||||||
|
- The seeded dashboard renders all first-slice panels.
|
||||||
|
- The user can add, remove, and adjust panels through server-rendered forms.
|
||||||
|
- Panel layout persists across sessions.
|
||||||
|
- Each panel is wrapped in `widgetEnvelope`.
|
||||||
|
- Annotating a panel opens the existing widget annotation flow.
|
||||||
|
- Existing Hubs and specialized dashboard routes still load.
|
||||||
|
- Focused tests or smoke checks cover seeding, config validation, route access,
|
||||||
|
and bounded query behavior.
|
||||||
|
|
||||||
|
## 10. Risks and Mitigations
|
||||||
|
|
||||||
|
| Risk | Mitigation |
|
||||||
|
|---|---|
|
||||||
|
| Scope grows into report builder | Limit first slice to six panel types and server-rendered forms |
|
||||||
|
| Existing dashboards are hard-coded | Extract only needed query/render fragments into new panel renderers |
|
||||||
|
| Panel config becomes unsafe JSON | Decode into Haskell ADTs and validate before querying |
|
||||||
|
| Role-aware defaults require missing schema | Use neutral default first; only best-effort stewardship hints |
|
||||||
|
| AutoRefresh refreshes too much | Bound all queries; defer per-panel refresh unless needed |
|
||||||
|
| Panel annotations lack stable identity | Require `dashboard_panels.widget_id` and `widgetEnvelope` |
|
||||||
|
| COUNT decode errors recur | Cast aggregate counts or decode as `Int64` in implementation |
|
||||||
|
|
||||||
|
## 11. Open Questions for FDD
|
||||||
|
|
||||||
|
1. Should table names use `personal_dashboards`/`dashboard_panels`, or a more
|
||||||
|
explicit `user_dashboards` prefix?
|
||||||
|
2. Should removed panels archive their linked widgets or mark them deprecated?
|
||||||
|
3. Should panel widgets be owned by the framework hub, or by the source hub when
|
||||||
|
a panel is hub-specific?
|
||||||
|
4. Should the first implementation allow multiple dashboards per user, or only
|
||||||
|
one default dashboard with schema ready for multiples?
|
||||||
|
5. Should `autoRefresh` wrap the whole dashboard action initially, or should
|
||||||
|
live panel fragments get their own actions?
|
||||||
|
6. Should watched hubs be a separate table in the first slice, or represented
|
||||||
|
as dashboard panel config only?
|
||||||
|
|
||||||
|
## 12. Recommendation
|
||||||
|
|
||||||
|
Proceed to FDD with a small, governed, server-rendered personal dashboard:
|
||||||
|
|
||||||
|
- One default dashboard per user, schema ready for multiples.
|
||||||
|
- Six first-slice panel types.
|
||||||
|
- `dashboard_panels.widget_id` as the governance anchor.
|
||||||
|
- Existing `panel` widget type for saved panel widgets.
|
||||||
|
- Whole-page `autoRefresh` initially, with bounded queries.
|
||||||
|
- Simple edit forms and no custom client runtime.
|
||||||
348
docs/research/personal-dashboard-current-state.md
Normal file
348
docs/research/personal-dashboard-current-state.md
Normal file
@@ -0,0 +1,348 @@
|
|||||||
|
# Personal Dashboard Current-State Research
|
||||||
|
|
||||||
|
**Workplan:** IHUB-WP-0020
|
||||||
|
**Date:** 2026-06-16
|
||||||
|
**Status:** Research deliverable for T01
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This note reviews the current inter-hub implementation before designing a
|
||||||
|
personal dashboard framework. The main finding is that inter-hub already has a
|
||||||
|
large set of server-rendered dashboard surfaces, governed widget identity, type
|
||||||
|
registries, annotations, event capture, hub health, API usage, marketplace, and
|
||||||
|
learning data. The personal dashboard should compose these capabilities instead
|
||||||
|
of inventing a separate dashboard product.
|
||||||
|
|
||||||
|
External dashboard products are used here only for pattern extraction. The
|
||||||
|
implementation direction remains IHP, HSX, Tailwind, server-rendered forms, and
|
||||||
|
existing IHF governance primitives.
|
||||||
|
|
||||||
|
## Evidence Reviewed
|
||||||
|
|
||||||
|
Repo files inspected for this note:
|
||||||
|
|
||||||
|
- `Web/Controller/Hubs.hs`
|
||||||
|
- `Web/Controller/Sessions.hs`
|
||||||
|
- `Web/FrontController.hs`
|
||||||
|
- `Web/Routes.hs`
|
||||||
|
- `Web/Types.hs`
|
||||||
|
- `Application/Schema.sql`
|
||||||
|
- `Application/Helper/View.hs`
|
||||||
|
- `Web/Controller/FederatedGovernance.hs`
|
||||||
|
- `Web/Controller/FederatedPolicyOverlays.hs`
|
||||||
|
- `Web/Controller/ApiDashboard.hs`
|
||||||
|
- `Web/Controller/MarketplaceDashboard.hs`
|
||||||
|
- `Web/Controller/LearningDashboard.hs`
|
||||||
|
- `docs/phase1-summary.md` through `docs/phase8-summary.md`
|
||||||
|
- `docs/ihp-ihf-mapping.md`
|
||||||
|
- `docs/widget-envelope-convention.md`
|
||||||
|
- Workplans IHUB-WP-0001 through IHUB-WP-0015 where dashboard scope was
|
||||||
|
introduced.
|
||||||
|
|
||||||
|
## Current Authenticated Entry Point
|
||||||
|
|
||||||
|
The public root and documentation pages already exist through IHUB-WP-0015 and
|
||||||
|
are registered last in `Web.FrontController`. The authenticated login flow still
|
||||||
|
redirects to `HubsAction`:
|
||||||
|
|
||||||
|
```haskell
|
||||||
|
login user
|
||||||
|
redirectTo HubsAction
|
||||||
|
```
|
||||||
|
|
||||||
|
`HubsAction` renders a table of hubs. It is useful as an admin list, but it is
|
||||||
|
not a personal daily operating surface.
|
||||||
|
|
||||||
|
The sidebar already links to several platform surfaces, including Hubs,
|
||||||
|
Learning, Ops Review, Federation, API Dashboard, Hub Registry, and Marketplace.
|
||||||
|
The personal dashboard should therefore become a new authenticated landing
|
||||||
|
route and a sidebar entry, while public root behavior remains unchanged.
|
||||||
|
|
||||||
|
## Existing Dashboard Inventory
|
||||||
|
|
||||||
|
| Surface | Action | Scope | Live? | Reuse potential |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| Hub list | `HubsAction` | Global hub table | No | Source for watched hubs and hub selector |
|
||||||
|
| Hub show | `ShowHubAction` | One hub | Yes | Recent events, annotations, widgets, manifest summary |
|
||||||
|
| Triage dashboard | `TriageDashboardAction` | One hub | Yes | Open candidates, recent escalations, annotation breakdown |
|
||||||
|
| Governance dashboard | `GovernanceDashboardAction` | One hub | Yes | Accepted candidates, requirements, decisions, traceability |
|
||||||
|
| Antifragility dashboard | `AntifragilityDashboardAction` | One hub | Yes | Deployments, outcome signals, recurrence leaderboard |
|
||||||
|
| Agent audit dashboard | `AgentAuditDashboardAction` | One hub context, global data | Yes | Agent proposals and review status |
|
||||||
|
| Adapter compatibility | `AdapterCompatibilityDashboardAction` | One hub | Yes | Adapter and contract compatibility panels |
|
||||||
|
| Friction heatmap | `FrictionHeatmapAction` | One hub | Yes | Widget friction summary |
|
||||||
|
| Bottleneck dashboard | `BottleneckDashboardAction` | One hub | Yes | Open bottlenecks |
|
||||||
|
| Hub health history | `HubHealthHistoryAction` | One hub | Yes | Health snapshot trend |
|
||||||
|
| Operational review board | `OperationalReviewBoardAction` | Global | Yes | Hub health, top friction, bottlenecks, propagations |
|
||||||
|
| Federated governance | `FederatedGovernanceDashboardAction` | Global | Yes | Ownership, routing, policy, stewardship, archive activity |
|
||||||
|
| Policy compliance | `PolicyComplianceDashboardAction` | Global | Yes | Active overlays and policy reference coverage |
|
||||||
|
| API dashboard | `ShowApiDashboardAction` | Global API consumers | Yes | Per-consumer request volume, error rate, last seen |
|
||||||
|
| Marketplace | `MarketplaceDashboardAction` | Global patterns/templates | Yes | Trending patterns, search/filter catalogue |
|
||||||
|
| Learning dashboard | `LearningDashboardAction` | Global learning memory | Yes | Insights, knowledge highlights, pattern rankings |
|
||||||
|
|
||||||
|
The reusable unit today is not a standalone panel renderer. It is a controller
|
||||||
|
query plus an HSX view fragment. WP-0021 should extract only the first small set
|
||||||
|
of renderers needed for the personal dashboard. A broad refactor of existing
|
||||||
|
dashboards is explicitly unnecessary for the first slice.
|
||||||
|
|
||||||
|
## AutoRefresh and Query Patterns
|
||||||
|
|
||||||
|
Most dashboard actions wrap the whole action with `autoRefresh do`. This is
|
||||||
|
simple and consistent with the existing IHP style. The current app does not have
|
||||||
|
a reusable per-panel refresh abstraction.
|
||||||
|
|
||||||
|
Useful bounded patterns already exist:
|
||||||
|
|
||||||
|
- `ShowHubAction` limits recent interaction events to 50 and annotations to 20.
|
||||||
|
- `GovernanceDashboardAction` limits recent decisions to 20.
|
||||||
|
- `LearningDashboardAction` limits correlations, rankings, insights, and
|
||||||
|
knowledge highlights.
|
||||||
|
- `MarketplaceDashboardAction` limits published patterns/templates and casts the
|
||||||
|
trending adoption count to integer.
|
||||||
|
|
||||||
|
Risky or broad patterns to avoid copying directly:
|
||||||
|
|
||||||
|
- Some hub dashboards fetch all related records for a hub and filter in memory.
|
||||||
|
That is acceptable for small scoped screens, but a personal dashboard should
|
||||||
|
bound every panel query by hub, time, status, and limit.
|
||||||
|
- Several global dashboards fetch all hubs or all decision records. A personal
|
||||||
|
view should either limit these or explicitly display only summarized rows.
|
||||||
|
- Raw `COUNT(*)` queries should cast to `integer` or decode as `Int64`. Recent
|
||||||
|
production work exposed PostgreSQL/Haskell decode failures when `COUNT(*)`
|
||||||
|
was decoded as `Int`.
|
||||||
|
|
||||||
|
Recommendation: first implementation can wrap the whole personal dashboard
|
||||||
|
action in `autoRefresh do`. The FDD should leave finer-grained panel refresh as
|
||||||
|
a later optimization unless a simple route-level fragment pattern emerges.
|
||||||
|
|
||||||
|
## Governed Widget and Annotation Constraints
|
||||||
|
|
||||||
|
`Application.Helper.View.widgetEnvelope` wraps a `Widget` record and injects
|
||||||
|
governance metadata:
|
||||||
|
|
||||||
|
- `data-widget-id`
|
||||||
|
- `data-widget-type`
|
||||||
|
- `data-hub-id`
|
||||||
|
- `data-capability-ref`
|
||||||
|
- `data-view-context`
|
||||||
|
- `data-policy-scope`
|
||||||
|
- `data-widget-version`
|
||||||
|
|
||||||
|
It also renders an Annotate link to the widget annotation view. The helper
|
||||||
|
warns when `view_context` is absent. Therefore, a saved personal dashboard panel
|
||||||
|
must not be treated as transient markup. It needs stable widget identity.
|
||||||
|
|
||||||
|
The registry seed includes a framework-level widget type named `panel`. That is
|
||||||
|
the best first choice for saved dashboard panels. A saved panel instance should
|
||||||
|
create or reference a `widgets` row with:
|
||||||
|
|
||||||
|
- `widget_type = 'panel'`
|
||||||
|
- `capability_ref = 'personal-dashboard.<panel-key>'`
|
||||||
|
- `view_context = 'personal-dashboard/<panel-key>'`
|
||||||
|
- `policy_scope = 'internal'`
|
||||||
|
- `status = 'active'`
|
||||||
|
|
||||||
|
The FDD should decide the owning hub rule. Recommended first slice: use the
|
||||||
|
framework hub for personal dashboard panel widgets and store source hub filters
|
||||||
|
in panel config. This keeps the personal dashboard itself governed by inter-hub
|
||||||
|
while still letting panels point at hub-specific data.
|
||||||
|
|
||||||
|
## Schema Available for First-Slice Panels
|
||||||
|
|
||||||
|
Existing tables with direct panel value:
|
||||||
|
|
||||||
|
- `hubs`
|
||||||
|
- `widgets`
|
||||||
|
- `widget_versions`
|
||||||
|
- `interaction_events`
|
||||||
|
- `annotations`
|
||||||
|
- `annotation_threads`
|
||||||
|
- `requirement_candidates`
|
||||||
|
- `triage_states`
|
||||||
|
- `reviewer_assignments`
|
||||||
|
- `requirements`
|
||||||
|
- `decision_records`
|
||||||
|
- `deployment_records`
|
||||||
|
- `outcome_signals`
|
||||||
|
- `friction_scores`
|
||||||
|
- `bottleneck_records`
|
||||||
|
- `hub_health_snapshots`
|
||||||
|
- `cross_hub_propagations`
|
||||||
|
- `widget_ownerships`
|
||||||
|
- `hub_routing_rules`
|
||||||
|
- `federated_policy_overlays`
|
||||||
|
- `stewardship_roles`
|
||||||
|
- `archive_records`
|
||||||
|
- `widget_type_registry`
|
||||||
|
- `event_type_registry`
|
||||||
|
- `annotation_category_registry`
|
||||||
|
- `policy_scope_registry`
|
||||||
|
- `hub_capability_manifests`
|
||||||
|
- `api_consumers`
|
||||||
|
- `api_request_log`
|
||||||
|
- `widget_patterns`
|
||||||
|
- `pattern_adoptions`
|
||||||
|
- `governance_templates`
|
||||||
|
- `governance_template_clones`
|
||||||
|
- `outcome_correlations`
|
||||||
|
- `pattern_performance_records`
|
||||||
|
- `adaptive_threshold_configs`
|
||||||
|
- `institutional_knowledge_entries`
|
||||||
|
- `learning_insights`
|
||||||
|
|
||||||
|
Important gaps:
|
||||||
|
|
||||||
|
- No `personal_dashboards` table.
|
||||||
|
- No `dashboard_panel_types` table.
|
||||||
|
- No `dashboard_panels` table.
|
||||||
|
- No saved watched-hub set or user preference table.
|
||||||
|
- No user role column.
|
||||||
|
- No panel config decoder/validator.
|
||||||
|
- No dedicated panel renderer module.
|
||||||
|
- No explicit default dashboard seeding helper.
|
||||||
|
|
||||||
|
## User and Role Model Findings
|
||||||
|
|
||||||
|
The `users` table has email, password hash, name, lockout fields, and created
|
||||||
|
time. It has no role. `stewardship_roles` stores `assigned_to` as text and is
|
||||||
|
hub-scoped. That can help infer operator relevance, but it is not a reliable
|
||||||
|
role foreign key.
|
||||||
|
|
||||||
|
Recommendation: do not add `users.role` for the first slice. Seed a neutral
|
||||||
|
default dashboard for all authenticated users, then allow the user to edit panel
|
||||||
|
layout and filters. If a default needs hub relevance, match active
|
||||||
|
`stewardship_roles.assigned_to` against user email or name as a best-effort
|
||||||
|
hint, not as an authorization rule.
|
||||||
|
|
||||||
|
## First-Slice Panel Candidates
|
||||||
|
|
||||||
|
The following panels are practical without broad refactoring:
|
||||||
|
|
||||||
|
| Panel key | Source | Default filter | Notes |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `watched-hubs` | `hubs`, latest `hub_health_snapshots` | all hubs, limit 12 | First panel can be neutral until watched hubs exist |
|
||||||
|
| `recent-interactions` | `interaction_events`, `widgets`, `hubs` | last 24h, limit 25 | Existing indexes support recent ordering |
|
||||||
|
| `triage-queue` | `requirement_candidates` | `status = 'open'`, limit 10 | Can join source widget/hub for context |
|
||||||
|
| `recent-decisions` | `decision_records` | last 30 days, limit 10 | Good governance reviewer entry point |
|
||||||
|
| `hub-health` | `hub_health_snapshots`, `bottleneck_records` | latest per hub, limit 12 | Needs bounded latest-per-hub query |
|
||||||
|
| `learning-digest` | `learning_insights`, `institutional_knowledge_entries` | latest, limit 5/5 | Already bounded in existing dashboard |
|
||||||
|
|
||||||
|
Panels to defer until after the framework is proven:
|
||||||
|
|
||||||
|
- `agent-proposals`
|
||||||
|
- `api-usage`
|
||||||
|
- `marketplace-trending`
|
||||||
|
- `my-annotations`
|
||||||
|
- `adapter-compatibility`
|
||||||
|
- `policy-compliance`
|
||||||
|
|
||||||
|
The deferred panels are valuable, but they are not needed to prove dashboard
|
||||||
|
persistence, layout, panel renderer dispatch, and governed panel identity.
|
||||||
|
|
||||||
|
## External Pattern Extraction
|
||||||
|
|
||||||
|
| System | Useful pattern | Translation for inter-hub |
|
||||||
|
|---|---|---|
|
||||||
|
| Grafana | Dashboard as saved grid of panels with variables and refresh behavior | Save panel rows plus hub/time filters; keep server-rendered refresh |
|
||||||
|
| Kibana dashboards | Saved searches and time range awareness | Treat panel query config as explicit, bounded, validated config |
|
||||||
|
| Retool/Appsmith | Widget catalogue and data binding | Use a server-side panel catalogue; avoid client runtime/data binding |
|
||||||
|
| Linear home | Personal "my work" aggregation across entities | Make the personal dashboard a daily work queue, not a clone of every dashboard |
|
||||||
|
| Notion linked databases | Multiple saved views over the same records | Let panels define filter/sort/display options against existing tables |
|
||||||
|
| Metabase | Question as a governed reusable unit | Treat panel renderer plus validated config as the reusable unit |
|
||||||
|
| Streamlit | Simple declarative layout vocabulary | Use predictable grid rows/spans and forms rather than drag-and-drop |
|
||||||
|
|
||||||
|
The key pattern across these systems is not visual complexity. It is that a
|
||||||
|
dashboard is a saved composition of bounded questions/panels with explicit
|
||||||
|
parameters. For inter-hub, those questions must remain governed IHF widgets.
|
||||||
|
|
||||||
|
## Answers to WP-0020 Research Questions
|
||||||
|
|
||||||
|
### Which existing fragments can become first-slice renderers?
|
||||||
|
|
||||||
|
Good first-slice candidates:
|
||||||
|
|
||||||
|
- Recent activity from `ShowHubAction`.
|
||||||
|
- Open candidate queue from `TriageDashboardAction`.
|
||||||
|
- Recent decisions from `GovernanceDashboardAction`.
|
||||||
|
- Latest hub health from `OperationalReviewBoardAction` and
|
||||||
|
`HubHealthHistoryAction`.
|
||||||
|
- Learning digest from `LearningDashboardAction`.
|
||||||
|
- Watched hubs from `HubsAction` plus latest health snapshots.
|
||||||
|
|
||||||
|
These can be implemented as new renderer functions that reuse the same model
|
||||||
|
queries and link to existing source dashboards for detail.
|
||||||
|
|
||||||
|
### Which configs are needed on day one?
|
||||||
|
|
||||||
|
Recommended day-one config options:
|
||||||
|
|
||||||
|
- `hubIds :: [Id Hub]` or `hubFilter :: Maybe [Id Hub]`
|
||||||
|
- `timeRange :: Last24Hours | Last7Days | Last30Days | AllTimeBounded`
|
||||||
|
- `limit :: Int`
|
||||||
|
- `sort :: NewestFirst | OldestFirst | HighestRiskFirst`
|
||||||
|
- `displayMode :: Compact | Detailed`
|
||||||
|
|
||||||
|
Config should be stored as JSONB but decoded into a Haskell ADT before use.
|
||||||
|
Invalid config should fall back to panel defaults and surface a non-fatal
|
||||||
|
operator warning.
|
||||||
|
|
||||||
|
### Which panels should live-refresh?
|
||||||
|
|
||||||
|
Live-refresh in the first slice:
|
||||||
|
|
||||||
|
- `recent-interactions`
|
||||||
|
- `triage-queue`
|
||||||
|
- `hub-health`
|
||||||
|
- `learning-digest`
|
||||||
|
|
||||||
|
Static per request in the first slice:
|
||||||
|
|
||||||
|
- `watched-hubs`
|
||||||
|
- `recent-decisions`
|
||||||
|
|
||||||
|
If the first implementation wraps the entire personal dashboard in
|
||||||
|
`autoRefresh`, all panels will refresh together. That is acceptable initially if
|
||||||
|
queries are bounded.
|
||||||
|
|
||||||
|
### How should saved panels map to governed widgets?
|
||||||
|
|
||||||
|
Each saved dashboard panel should own a `widgets` row and store the id on
|
||||||
|
`dashboard_panels.widget_id`. The panel renderer should call `widgetEnvelope`
|
||||||
|
with that widget. This gives stable annotation and interaction capture identity.
|
||||||
|
|
||||||
|
Panel lifecycle:
|
||||||
|
|
||||||
|
1. User adds a panel.
|
||||||
|
2. Controller creates `dashboard_panels` row.
|
||||||
|
3. Controller creates linked `widgets` row with `widget_type = 'panel'`.
|
||||||
|
4. Controller creates a `widget_versions` snapshot for the panel widget.
|
||||||
|
5. Show view renders the panel through `widgetEnvelope`.
|
||||||
|
6. Removing a panel should mark the widget archived or deprecated, not delete
|
||||||
|
interaction history.
|
||||||
|
|
||||||
|
### What should be deferred?
|
||||||
|
|
||||||
|
Defer:
|
||||||
|
|
||||||
|
- Drag-and-drop layout.
|
||||||
|
- Shared dashboards.
|
||||||
|
- Team dashboards.
|
||||||
|
- External datasource connectors.
|
||||||
|
- Client-side data fetching.
|
||||||
|
- Per-panel WebSocket channels.
|
||||||
|
- Full refactor of existing dashboard views.
|
||||||
|
- Complex role model.
|
||||||
|
- Dashboard marketplace/templates beyond one seeded default.
|
||||||
|
|
||||||
|
## Recommendations for T02/T03
|
||||||
|
|
||||||
|
1. Define the personal dashboard as the authenticated landing page, not a
|
||||||
|
replacement for existing source dashboards.
|
||||||
|
2. Use a small panel catalogue for the first implementation.
|
||||||
|
3. Persist dashboard/panel rows in relational tables and panel config in JSONB.
|
||||||
|
4. Decode panel config into explicit Haskell ADTs before querying.
|
||||||
|
5. Give every saved panel stable `Widget` identity.
|
||||||
|
6. Use the existing `panel` widget type.
|
||||||
|
7. Keep the default dashboard neutral and editable.
|
||||||
|
8. Bound every panel query.
|
||||||
|
9. Cast SQL aggregate counts to integer when decoding as `Int`.
|
||||||
|
10. Keep implementation tasks small enough to avoid a cross-dashboard refactor.
|
||||||
@@ -4,11 +4,11 @@ type: workplan
|
|||||||
title: "Personal Dashboard Framework"
|
title: "Personal Dashboard Framework"
|
||||||
domain: inter_hub
|
domain: inter_hub
|
||||||
repo: inter-hub
|
repo: inter-hub
|
||||||
status: backlog
|
status: finished
|
||||||
owner: tegwick
|
owner: tegwick
|
||||||
topic_slug: inter_hub
|
topic_slug: inter_hub
|
||||||
created: "2026-05-03"
|
created: "2026-05-03"
|
||||||
updated: "2026-06-07"
|
updated: "2026-06-16"
|
||||||
phase: 13
|
phase: 13
|
||||||
state_hub_workstream_id: "72fc022b-0196-492a-aaba-3475f8768f06"
|
state_hub_workstream_id: "72fc022b-0196-492a-aaba-3475f8768f06"
|
||||||
---
|
---
|
||||||
@@ -17,283 +17,399 @@ state_hub_workstream_id: "72fc022b-0196-492a-aaba-3475f8768f06"
|
|||||||
|
|
||||||
## Goal
|
## Goal
|
||||||
|
|
||||||
Design and implement a personal dashboard framework that allows individual users to
|
Design the first personal dashboard layer for inter-hub: an authenticated,
|
||||||
compose, configure, and persist a view of the inter-hub platform tailored to their
|
per-user landing surface that composes the most important existing hub,
|
||||||
role and focus. The dashboard is the post-login landing page and the primary daily
|
governance, API, marketplace, and learning signals into a configurable daily
|
||||||
driver surface for hub operators, governance reviewers, and AI orchestrators.
|
operator view.
|
||||||
|
|
||||||
## Motivation
|
This workplan is now a design and implementation-planning workplan. It should
|
||||||
|
produce the current-state audit, product requirements, functional design, and
|
||||||
|
follow-on implementation workplan needed to build the feature safely.
|
||||||
|
|
||||||
The current post-login experience drops the user on a raw Hubs list. As inter-hub
|
## Review Update: 2026-06-15
|
||||||
grows to 12+ phases of functionality, users need a curated, role-aware entry point
|
|
||||||
that surfaces the signals that matter to them without requiring manual navigation.
|
|
||||||
The dashboard is also the natural home for cross-cutting observability (recent
|
|
||||||
decisions, open candidates, outcome signals) that cuts across the current
|
|
||||||
controller-per-entity navigation.
|
|
||||||
|
|
||||||
---
|
This workplan was reviewed against the current repository state and updated
|
||||||
|
from `backlog` to `ready`.
|
||||||
|
|
||||||
|
The original version assumed inter-hub mainly had a raw Hubs list and needed a
|
||||||
|
greenfield dashboard framework. That assumption is outdated. The repo now has
|
||||||
|
many dashboard-like surfaces and governed interaction primitives that should be
|
||||||
|
reused instead of bypassed:
|
||||||
|
|
||||||
|
- Public root/intro pages exist from IHUB-WP-0015; the authenticated login flow
|
||||||
|
still redirects to `HubsAction`.
|
||||||
|
- Hub-level dashboard actions already exist in `Web.Controller.Hubs`, including
|
||||||
|
hub show, triage, governance, antifragility, agent audit, adapter
|
||||||
|
compatibility, friction heatmap, bottleneck, hub health history, and the
|
||||||
|
operational review board.
|
||||||
|
- Cross-hub and platform dashboards already exist: federated governance, policy
|
||||||
|
compliance, API usage, marketplace, and learning dashboard.
|
||||||
|
- The governed interaction substrate is mature: `widgets`, `widget_versions`,
|
||||||
|
`interaction_events`, `annotations`, type registries, hub manifests,
|
||||||
|
ownership/routing, API request logs, hub health snapshots, learning insights,
|
||||||
|
and institutional knowledge are all present.
|
||||||
|
- There is no personal dashboard schema, controller, saved panel catalogue,
|
||||||
|
user preference model, or role-aware default layout yet.
|
||||||
|
- Existing dashboards are mostly hard-coded controller queries plus HSX view
|
||||||
|
fragments. They are useful source material, but they are not yet reusable
|
||||||
|
panel renderers.
|
||||||
|
- The `users` table has no role column. `stewardship_roles.assigned_to` is text
|
||||||
|
and hub-scoped, so role-aware defaults must be designed carefully instead of
|
||||||
|
assuming a user-role foreign key exists.
|
||||||
|
|
||||||
|
The updated scope is therefore integration-first: define a personal dashboard
|
||||||
|
contract that reuses existing data sources and view patterns, then introduce a
|
||||||
|
small panel renderer abstraction only where it removes real duplication.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
### In Scope
|
||||||
|
|
||||||
|
- Authenticated personal dashboard route and post-login redirect design.
|
||||||
|
- Per-user saved dashboard record with ordered panel instances.
|
||||||
|
- A server-rendered panel catalogue backed by existing inter-hub models.
|
||||||
|
- Simple layout editing through IHP forms; no drag-and-drop in the first slice.
|
||||||
|
- Hub/time filters for panels where the underlying queries already support
|
||||||
|
bounded data.
|
||||||
|
- Panel-level governance: each rendered saved panel must be annotatable and
|
||||||
|
event-capturable through the existing `widgetEnvelope` convention.
|
||||||
|
- A migration path that reuses current dashboard queries before attempting broad
|
||||||
|
refactors.
|
||||||
|
|
||||||
|
### Out of Scope for the First Implementation Workplan
|
||||||
|
|
||||||
|
- Client-side dashboard frameworks or client-side data fetching.
|
||||||
|
- External datasource connectors.
|
||||||
|
- Shared/team dashboards.
|
||||||
|
- Mobile-native layout editing.
|
||||||
|
- Drag-and-drop layout editing.
|
||||||
|
- A general purpose report builder.
|
||||||
|
- Rewriting every existing dashboard into panel renderers.
|
||||||
|
|
||||||
|
## Current Design Constraints
|
||||||
|
|
||||||
|
- Server-rendered IHP views remain the default. `autoRefresh` is acceptable for
|
||||||
|
panels that already use live refresh patterns.
|
||||||
|
- Tailwind and existing HSX view conventions should be reused.
|
||||||
|
- Runtime panel config may be stored as JSONB, but renderer code should decode
|
||||||
|
into explicit Haskell config types before use.
|
||||||
|
- Do not create an ungoverned visual component layer. A saved dashboard panel
|
||||||
|
must either reference or create a `Widget` row, most likely using the existing
|
||||||
|
framework-level `panel` widget type, so annotations and interaction events
|
||||||
|
remain first-class IHF artifacts.
|
||||||
|
- Avoid adding a `users.role` column unless the PRS/FDD proves it is needed.
|
||||||
|
Prefer defaults derived from current user identity, stewardship assignments,
|
||||||
|
selected watched hubs, or explicit dashboard template choice.
|
||||||
|
|
||||||
|
## Proposed First-Slice Panel Catalogue
|
||||||
|
|
||||||
|
The initial catalogue should be limited to panels that can be built from
|
||||||
|
existing tables and controllers:
|
||||||
|
|
||||||
|
| Panel key | Label | Source surface/data | Live? |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `watched-hubs` | Watched Hubs | `hubs`, `hub_health_snapshots`, optional saved hub filter | No |
|
||||||
|
| `recent-interactions` | Recent Activity | `interaction_events` plus `widgets` and `hubs` | Yes |
|
||||||
|
| `triage-queue` | Triage Queue | open `requirement_candidates` | Yes |
|
||||||
|
| `recent-decisions` | Recent Decisions | `decision_records`, requirements, candidates | No |
|
||||||
|
| `hub-health` | Hub Health | latest `hub_health_snapshots`, bottlenecks | Yes |
|
||||||
|
| `agent-proposals` | Agent Proposals | `agent_proposals`, `agent_review_records` | No |
|
||||||
|
| `api-usage` | API Usage | `api_consumers`, `api_request_log` | Yes |
|
||||||
|
| `marketplace-trending` | Marketplace Trending | `widget_patterns`, adoptions, templates | No |
|
||||||
|
| `learning-digest` | Learning Digest | `learning_insights`, `institutional_knowledge_entries` | Yes |
|
||||||
|
| `my-annotations` | My Annotations | `annotations` filtered by current user when available | No |
|
||||||
|
|
||||||
|
The implementation workplan should start with a smaller subset if needed:
|
||||||
|
`watched-hubs`, `recent-interactions`, `triage-queue`, `recent-decisions`,
|
||||||
|
`hub-health`, and `learning-digest` are enough to prove the framework.
|
||||||
|
|
||||||
## Tasks
|
## Tasks
|
||||||
|
|
||||||
### T01 — Research: Dashboard frameworks and patterns for inspiration
|
### T01 - Current-state audit and dashboard pattern research
|
||||||
|
|
||||||
```task
|
```task
|
||||||
id: IHUB-WP-0020-T01
|
id: IHUB-WP-0020-T01
|
||||||
status: todo
|
status: done
|
||||||
priority: high
|
priority: high
|
||||||
state_hub_task_id: "6074f195-636b-4517-b6d1-eb3c57394a82"
|
state_hub_task_id: "6074f195-636b-4517-b6d1-eb3c57394a82"
|
||||||
```
|
```
|
||||||
|
|
||||||
Survey existing dashboard systems to extract patterns that are re-implementable in
|
Produce a short research note that starts with the current inter-hub codebase,
|
||||||
Haskell / IHP / Tailwind under inter-hub's design constraints (server-rendered,
|
then uses external dashboard systems only for secondary inspiration.
|
||||||
type-safe, governed).
|
|
||||||
|
|
||||||
**Research targets:**
|
Required current-state inventory:
|
||||||
|
|
||||||
|
- Existing routes and views that behave like dashboards.
|
||||||
|
- Existing `autoRefresh` usage and query patterns that are safe to reuse.
|
||||||
|
- Existing type registry, `Widget`, `widgetEnvelope`, annotation, and event
|
||||||
|
capture constraints.
|
||||||
|
- Existing tables that can power first-slice personal panels.
|
||||||
|
- Gaps: personal dashboard persistence, panel catalogue, saved filters, layout
|
||||||
|
model, and user preference/defaulting model.
|
||||||
|
|
||||||
|
External systems may still be sampled, but the output should focus on patterns
|
||||||
|
that are practical in IHP/HSX/Tailwind:
|
||||||
|
|
||||||
| System | What to extract |
|
| System | What to extract |
|
||||||
|---|---|
|
|---|---|
|
||||||
| **Grafana** | Panel/grid layout model; datasource abstraction; variable-driven filtering |
|
| Grafana | Panel/grid layout model, dashboard variables, bounded refresh |
|
||||||
| **Kibana (dashboards)** | Saved-search panels; time-range awareness; role-based visibility |
|
| Kibana dashboards | Saved-search panels, time range filters, role visibility |
|
||||||
| **Retool / Appsmith** | Widget catalogue approach; drag-grid layout; data binding model |
|
| Retool/Appsmith | Widget catalogue and data binding concepts, not their client runtime |
|
||||||
| **Linear (home view)** | Flat "My Work" aggregation across entities; priority surfacing |
|
| Linear home view | Flat "my work" aggregation across entities |
|
||||||
| **Notion (linked databases)** | Filter/sort persistence per user; view types (table, board, calendar) |
|
| Notion linked databases | Saved filters/sorts as user-facing views |
|
||||||
| **Observable Framework** | Reactive cell model; markdown + code co-location |
|
| Metabase | Question-as-unit model and governed saved queries |
|
||||||
| **Metabase** | Question-as-unit; dashboard as ordered collection of questions |
|
| Streamlit | Declarative layout vocabulary suitable for server rendering |
|
||||||
| **Streamlit** | Declarative layout (columns, expanders); pure functional rendering loop |
|
|
||||||
|
|
||||||
**Questions to answer per system:**
|
Questions to answer:
|
||||||
1. How is a dashboard persisted? (JSON blob, relational rows, code-as-config?)
|
|
||||||
2. How is a widget/panel parameterised? (datasource, filter, display options)
|
|
||||||
3. How is layout described? (fixed grid, CSS grid, drag-and-drop, responsive breakpoints)
|
|
||||||
4. How is per-user state separated from shared/team state?
|
|
||||||
5. What is the update model? (full-page reload, WebSocket push, polling, partial HTMX swap)
|
|
||||||
6. How are access controls expressed at panel level?
|
|
||||||
|
|
||||||
**IHP/Haskell-specific constraints to keep in mind:**
|
1. Which existing inter-hub dashboard fragments can become first-slice panel
|
||||||
- Server-rendered by default; AutoRefresh (WebSocket) available for live data
|
renderers without broad refactoring?
|
||||||
- No client-side state management library; JS must be minimal
|
2. Which panel configs must exist on day one: hub filter, time range, limit,
|
||||||
- Type safety from DB schema → view layer is a first-class constraint
|
display mode, or sort order?
|
||||||
- Tailwind CSS; no component library
|
3. Which panels need live refresh, and which should stay static per request?
|
||||||
|
4. How should each saved panel map to a governed `Widget` row?
|
||||||
|
5. What should be explicitly deferred to avoid building a report builder?
|
||||||
|
|
||||||
**Exit criteria:** Research notes written in `docs/research/dashboard-frameworks.md`.
|
Exit criteria: `docs/research/personal-dashboard-current-state.md` exists and
|
||||||
|
has enough evidence to drive the PRS.
|
||||||
|
|
||||||
|
Completion note (2026-06-16): added
|
||||||
|
`docs/research/personal-dashboard-current-state.md`, covering the current
|
||||||
|
dashboard inventory, AutoRefresh/query patterns, governed widget constraints,
|
||||||
|
first-slice panel candidates, external pattern extraction, and T02/T03
|
||||||
|
recommendations.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### T02 — Product Requirements Specification (PRS)
|
### T02 - Product Requirements Specification
|
||||||
|
|
||||||
```task
|
```task
|
||||||
id: IHUB-WP-0020-T02
|
id: IHUB-WP-0020-T02
|
||||||
status: todo
|
status: done
|
||||||
priority: high
|
priority: high
|
||||||
depends_on: T01
|
depends_on: T01
|
||||||
state_hub_task_id: "698304bc-b91a-42e2-a617-b3ddbf749174"
|
state_hub_task_id: "698304bc-b91a-42e2-a617-b3ddbf749174"
|
||||||
```
|
```
|
||||||
|
|
||||||
Produce a formal PRS for the Personal Dashboard Framework based on T01 findings and
|
Produce a formal PRS based on T01 and the current implementation.
|
||||||
inter-hub's design principles.
|
|
||||||
|
|
||||||
**Required sections:**
|
Required sections:
|
||||||
|
|
||||||
1. **Problem statement** — who uses the dashboard, what decisions they make with it,
|
1. Problem statement: authenticated users currently land on the Hubs list and
|
||||||
what pain the current flat-nav approach causes
|
must manually navigate to specialized dashboards to answer daily operating
|
||||||
|
questions.
|
||||||
|
2. Personas:
|
||||||
|
- Hub operator: watches hub health, recent events, candidates, and
|
||||||
|
bottlenecks.
|
||||||
|
- Governance reviewer: triages candidates, decisions, policy coverage, and
|
||||||
|
annotations.
|
||||||
|
- AI orchestrator: watches agent proposals, review outcomes, and learning
|
||||||
|
signals.
|
||||||
|
- Platform admin: watches API usage, hub registry health, manifests, and
|
||||||
|
cross-hub propagation.
|
||||||
|
3. Core requirements using MoSCoW:
|
||||||
|
- Must: per-user saved dashboard, seeded default dashboard, panel catalogue,
|
||||||
|
server-rendered panels, persisted layout, governed panel widget identity,
|
||||||
|
post-login route design, bounded panel queries.
|
||||||
|
- Should: hub/time filters, simple edit mode, live refresh on selected
|
||||||
|
panels, keyboard-accessible forms, link-outs to existing source
|
||||||
|
dashboards.
|
||||||
|
- Could: dashboard templates, saved watched-hub sets, shared dashboards,
|
||||||
|
richer display modes.
|
||||||
|
- Won't: drag-and-drop, external datasources, client-side fetching, mobile
|
||||||
|
layout editor, complete refactor of existing dashboards.
|
||||||
|
4. Non-functional requirements:
|
||||||
|
- First paint target remains sub-second for seeded dashboards with bounded
|
||||||
|
panel queries.
|
||||||
|
- Panel queries must use limits and existing indexes or propose new indexes.
|
||||||
|
- Dashboard save/load must be simple transactional IHP controller work.
|
||||||
|
- No new JS framework.
|
||||||
|
5. Governance fit:
|
||||||
|
- Saved panel instances are governed IHF widgets or reference governed
|
||||||
|
widgets.
|
||||||
|
- Panel views use `widgetEnvelope`.
|
||||||
|
- Panel interactions emit existing event types where possible.
|
||||||
|
- Annotations attach to the panel widget identity, not to a transient DOM
|
||||||
|
block.
|
||||||
|
|
||||||
2. **User personas**
|
Exit criteria: `docs/prs/personal-dashboard-prs.md` exists and is ready for
|
||||||
- Hub Operator: monitors activity within their hub; wants recent events, open candidates
|
FDD work.
|
||||||
- Governance Reviewer: triages candidates, reviews decisions; needs queue and signal views
|
|
||||||
- AI Orchestrator: monitors agent proposals, outcome correlations; needs performance panels
|
|
||||||
- Platform Admin: watches system health, API usage, learning throughput
|
|
||||||
|
|
||||||
3. **Core requirements (MoSCoW)**
|
Completion note (2026-06-16): added
|
||||||
- Must: per-user dashboard persisted in DB; selectable panels from a catalogue;
|
`docs/prs/personal-dashboard-prs.md`, defining the problem statement,
|
||||||
layout preserved across sessions; role-aware default layout on first login
|
personas, MoSCoW requirements, first-slice panel catalogue, governance
|
||||||
- Should: panel-level filtering (by hub, by time range); live-update via AutoRefresh
|
requirements, acceptance criteria, risks, and FDD open questions.
|
||||||
for signal panels; keyboard-navigable
|
|
||||||
- Could: drag-and-drop layout editing; shared/team dashboards; dashboard templates
|
|
||||||
- Won't (Phase 13): mobile-native layout; client-side data fetching; external datasources
|
|
||||||
|
|
||||||
4. **Non-functional requirements**
|
|
||||||
- First paint < 500 ms (server-rendered, no JS data fetching)
|
|
||||||
- Dashboard save/load < 100 ms
|
|
||||||
- Each panel query < 200 ms (indexed, bounded result sets)
|
|
||||||
- Zero JS frameworks; AutoRefresh WebSocket for live panels only
|
|
||||||
|
|
||||||
5. **Governance fit** — dashboard widgets are themselves `Widget` records in the IHF
|
|
||||||
sense; `InteractionEvent`s recorded on dashboard interactions; annotations possible
|
|
||||||
on any panel
|
|
||||||
|
|
||||||
**Exit criteria:** `docs/prs/dashboard-framework-prs.md` reviewed and accepted.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### T03 — Functional Design Document (FDD)
|
### T03 - Functional Design Document
|
||||||
|
|
||||||
```task
|
```task
|
||||||
id: IHUB-WP-0020-T03
|
id: IHUB-WP-0020-T03
|
||||||
status: todo
|
status: done
|
||||||
priority: high
|
priority: high
|
||||||
depends_on: T02
|
depends_on: T02
|
||||||
state_hub_task_id: "438e5771-a043-4f26-a1ce-994ed478a760"
|
state_hub_task_id: "438e5771-a043-4f26-a1ce-994ed478a760"
|
||||||
```
|
```
|
||||||
|
|
||||||
Translate the PRS into a concrete functional design covering schema, component model,
|
Translate the PRS into a concrete FDD covering schema, controller actions,
|
||||||
rendering pipeline, and layout system. This is the authoritative reference for implementation.
|
panel renderer contract, layout, seed/default behavior, and migration strategy.
|
||||||
|
|
||||||
**Required sections:**
|
The FDD must update the old greenfield schema sketch. A likely shape is:
|
||||||
|
|
||||||
#### 3.1 Data model
|
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
-- A user's named dashboard
|
CREATE TABLE personal_dashboards (
|
||||||
CREATE TABLE dashboards (
|
|
||||||
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
||||||
user_id UUID NOT NULL REFERENCES users(id),
|
user_id UUID NOT NULL REFERENCES users(id),
|
||||||
name TEXT NOT NULL,
|
name TEXT NOT NULL,
|
||||||
is_default BOOLEAN NOT NULL DEFAULT FALSE,
|
is_default BOOLEAN NOT NULL DEFAULT FALSE,
|
||||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||||
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||||
);
|
);
|
||||||
|
|
||||||
-- An instance of a panel type on a dashboard, with position
|
CREATE TABLE dashboard_panel_types (
|
||||||
CREATE TABLE dashboard_panels (
|
|
||||||
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
||||||
dashboard_id UUID NOT NULL REFERENCES dashboards(id) ON DELETE CASCADE,
|
key TEXT NOT NULL UNIQUE,
|
||||||
panel_type TEXT NOT NULL, -- FK to panel_type_registry
|
|
||||||
config JSONB NOT NULL DEFAULT '{}',
|
|
||||||
col INT NOT NULL DEFAULT 0,
|
|
||||||
row INT NOT NULL DEFAULT 0,
|
|
||||||
col_span INT NOT NULL DEFAULT 1,
|
|
||||||
row_span INT NOT NULL DEFAULT 1,
|
|
||||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
|
||||||
);
|
|
||||||
|
|
||||||
-- Registry of available panel types
|
|
||||||
CREATE TABLE panel_type_registry (
|
|
||||||
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
|
||||||
name TEXT NOT NULL UNIQUE,
|
|
||||||
label TEXT NOT NULL,
|
label TEXT NOT NULL,
|
||||||
description TEXT,
|
description TEXT,
|
||||||
default_config JSONB NOT NULL DEFAULT '{}',
|
default_config JSONB NOT NULL DEFAULT '{}',
|
||||||
requires_hub BOOLEAN NOT NULL DEFAULT FALSE,
|
default_col_span INT NOT NULL DEFAULT 4,
|
||||||
live_update BOOLEAN NOT NULL DEFAULT FALSE
|
default_row_span INT NOT NULL DEFAULT 1,
|
||||||
|
live_update BOOLEAN NOT NULL DEFAULT FALSE,
|
||||||
|
status TEXT NOT NULL DEFAULT 'active'
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE dashboard_panels (
|
||||||
|
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
|
||||||
|
dashboard_id UUID NOT NULL REFERENCES personal_dashboards(id) ON DELETE CASCADE,
|
||||||
|
panel_type_id UUID NOT NULL REFERENCES dashboard_panel_types(id),
|
||||||
|
widget_id UUID NOT NULL REFERENCES widgets(id),
|
||||||
|
config JSONB NOT NULL DEFAULT '{}',
|
||||||
|
col INT NOT NULL DEFAULT 0,
|
||||||
|
row INT NOT NULL DEFAULT 0,
|
||||||
|
col_span INT NOT NULL DEFAULT 4,
|
||||||
|
row_span INT NOT NULL DEFAULT 1,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||||
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||||
);
|
);
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 3.2 Panel catalogue (Phase 13 scope)
|
The FDD must also resolve:
|
||||||
|
|
||||||
| Panel type name | Label | Description | Live? |
|
- Naming: whether tables should use `personal_dashboards` or another prefix to
|
||||||
|---|---|---|---|
|
avoid confusing them with existing dashboard actions.
|
||||||
| `recent-interactions` | Recent Activity | Latest interaction events across watched hubs | Yes |
|
- Panel config: JSONB storage plus explicit Haskell ADT decoding and validation.
|
||||||
| `open-candidates` | Open Candidates | Requirement candidates awaiting triage | No |
|
- Governance identity: how `dashboard_panels.widget_id` is created, versioned,
|
||||||
| `decision-queue` | Decision Queue | Decisions pending review | No |
|
and named.
|
||||||
| `outcome-signals` | Outcome Signals | Recent outcome signal summary | Yes |
|
- Renderer contract:
|
||||||
| `hub-health` | Hub Health | Health snapshot per hub | No |
|
|
||||||
| `agent-proposals` | Agent Proposals | Open AI agent proposals | No |
|
|
||||||
| `learning-digest` | Learning Digest | Latest institutional knowledge entries | No |
|
|
||||||
| `my-annotations` | My Annotations | Annotations by the current user | No |
|
|
||||||
|
|
||||||
#### 3.3 Layout system
|
|
||||||
|
|
||||||
12-column CSS grid; panels occupy `col_span` columns and `row_span` rows.
|
|
||||||
Row height fixed at 240px. No drag-and-drop in Phase 13; layout edited via
|
|
||||||
form fields (col, row, span). Responsive: collapse to single column below 768px.
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────────┐
|
|
||||||
│ [Recent Activity ×6] [Decision Queue ×3] [Hub ×3]│
|
|
||||||
│ │
|
|
||||||
├─────────────────────────────────────────────────────┤
|
|
||||||
│ [Open Candidates ×4] [Outcome Signals ×4] [My ×4] │
|
|
||||||
└─────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3.4 Rendering pipeline
|
|
||||||
|
|
||||||
```
|
|
||||||
GET /Dashboard
|
|
||||||
→ DashboardController#show
|
|
||||||
→ fetch dashboard + panels (ordered by row, col)
|
|
||||||
→ for each panel: dispatch to panel renderer (panelHtml panelType config)
|
|
||||||
→ embed in DashboardView with CSS grid layout
|
|
||||||
→ AutoRefresh wraps live panels only
|
|
||||||
```
|
|
||||||
|
|
||||||
Each panel renderer is a Haskell function:
|
|
||||||
```haskell
|
```haskell
|
||||||
type PanelRenderer = PanelConfig -> ModelContext -> IO Html
|
data DashboardPanelConfig
|
||||||
renderPanel :: Text -> PanelConfig -> ModelContext -> IO Html
|
= WatchedHubsConfig WatchedHubsOptions
|
||||||
renderPanel "recent-interactions" = renderRecentInteractions
|
| RecentInteractionsConfig RecentInteractionsOptions
|
||||||
renderPanel "open-candidates" = renderOpenCandidates
|
| TriageQueueConfig TriageQueueOptions
|
||||||
...
|
| RecentDecisionsConfig RecentDecisionsOptions
|
||||||
|
| HubHealthConfig HubHealthOptions
|
||||||
|
| LearningDigestConfig LearningDigestOptions
|
||||||
|
|
||||||
|
renderDashboardPanel
|
||||||
|
:: DashboardPanelType
|
||||||
|
-> DashboardPanel
|
||||||
|
-> DashboardPanelConfig
|
||||||
|
-> ModelContext
|
||||||
|
-> IO Html
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 3.5 Edit flow
|
- Layout: 12-column grid on desktop, single-column below the existing Tailwind
|
||||||
|
breakpoint, stable row/span constraints, no drag-and-drop in the first slice.
|
||||||
|
- Routes/actions:
|
||||||
|
- `PersonalDashboardAction`
|
||||||
|
- `EditPersonalDashboardAction`
|
||||||
|
- `UpdatePersonalDashboardAction`
|
||||||
|
- `AddDashboardPanelAction`
|
||||||
|
- `UpdateDashboardPanelAction`
|
||||||
|
- `RemoveDashboardPanelAction`
|
||||||
|
- Login behavior: `CreateSessionAction` should redirect to the personal
|
||||||
|
dashboard after authentication, while public root pages remain unchanged.
|
||||||
|
- Defaulting model: seed a default dashboard on first visit without requiring a
|
||||||
|
`users.role` column.
|
||||||
|
- Query safety: each panel query must be bounded, indexed, and compatible with
|
||||||
|
current PostgreSQL type decoding practices such as casting `COUNT(*)` to
|
||||||
|
integer when read as `Int`.
|
||||||
|
- Tests and smoke checks needed for the follow-on implementation workplan.
|
||||||
|
|
||||||
`GET /Dashboard/Edit` → grid with inline forms per panel (col/row/span inputs) +
|
Exit criteria: `docs/fdd/personal-dashboard-fdd.md` exists, schema decisions
|
||||||
"Add Panel" dropdown from `panel_type_registry`. `POST /Dashboard` saves layout.
|
are concrete enough to implement, and open questions are explicitly listed.
|
||||||
No JavaScript needed for basic edit; optional HTMX for panel preview.
|
|
||||||
|
|
||||||
#### 3.6 Default dashboard on first login
|
Completion note (2026-06-16): added
|
||||||
|
`docs/fdd/personal-dashboard-fdd.md`, resolving schema names, panel config
|
||||||
`afterLoginRedirectPath` (in `SessionsControllerConfig`) redirects to `/Dashboard`.
|
typing, renderer/view-model shape, default seeding, governed panel widget
|
||||||
On first visit, `DashboardController` checks for an existing dashboard; if absent,
|
lifecycle, query constraints, routes, layout, tests, and handoff shape for
|
||||||
creates a default one seeded from the user's role (determined by a `role` field
|
IHUB-WP-0021.
|
||||||
to be added to `users`, or a simple heuristic based on existing data).
|
|
||||||
|
|
||||||
**Exit criteria:** FDD reviewed; schema migrations drafted; panel catalogue agreed.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### T04 — Implementation workplan
|
### T04 - Implementation workplan
|
||||||
|
|
||||||
```task
|
```task
|
||||||
id: IHUB-WP-0020-T04
|
id: IHUB-WP-0020-T04
|
||||||
status: todo
|
status: done
|
||||||
priority: medium
|
priority: medium
|
||||||
depends_on: T03
|
depends_on: T03
|
||||||
state_hub_task_id: "970aa221-7e17-4500-8b37-9c98676280b1"
|
state_hub_task_id: "970aa221-7e17-4500-8b37-9c98676280b1"
|
||||||
```
|
```
|
||||||
|
|
||||||
Break T03's FDD into a detailed, sequenced task list suitable for execution as a new
|
Create the execution workplan for implementation as `IHUB-WP-0021`.
|
||||||
workplan (IHUB-WP-0021). Each task must have a clear entry/exit criterion and fit within
|
|
||||||
the 8k token soft budget.
|
|
||||||
|
|
||||||
**Expected task structure of IHUB-WP-0021:**
|
Expected task structure for `IHUB-WP-0021`:
|
||||||
|
|
||||||
```
|
| Task | Focus |
|
||||||
T01 Schema migration: dashboards, dashboard_panels, panel_type_registry
|
|---|---|
|
||||||
T02 Seed: default panel types in panel_type_registry
|
| T01 | Schema migration for personal dashboards, panel types, and panel instances |
|
||||||
T03 DashboardController — show action (fetch + render)
|
| T02 | Seed dashboard panel types and any required framework `panel` widgets/type vocabulary |
|
||||||
T04 Panel renderers — first 3 panels (recent-interactions, open-candidates, decision-queue)
|
| T03 | Add controller/action/route skeleton and default dashboard lookup/seed helper |
|
||||||
T05 DashboardView — CSS grid layout
|
| T04 | Implement first three renderers: watched hubs, recent interactions, triage queue |
|
||||||
T06 Panel renderers — remaining 5 panels
|
| T05 | Implement dashboard show view and responsive CSS grid |
|
||||||
T07 Dashboard edit flow (layout form, add/remove panels)
|
| T06 | Implement remaining first-slice renderers: recent decisions, hub health, learning digest |
|
||||||
T08 Default dashboard seeding on first login
|
| T07 | Implement edit flow: reorder/update layout, add/remove panels, validate config |
|
||||||
T09 afterLoginRedirectPath → /Dashboard
|
| T08 | Add governed widget identity creation and `widgetEnvelope` wrapping for panels |
|
||||||
T10 AutoRefresh for live panels (recent-interactions, outcome-signals)
|
| T09 | Redirect successful login to the personal dashboard |
|
||||||
T11 Role-aware default layout
|
| T10 | Add `autoRefresh` only around selected live panels or the whole page if finer wrapping is not practical |
|
||||||
T12 Smoke tests
|
| T11 | Add focused tests for seeding, panel config validation, route access, and bounded queries |
|
||||||
```
|
| T12 | Manual smoke: login, seeded dashboard, edit layout, annotate a panel, verify source dashboards still load |
|
||||||
|
|
||||||
**Exit criteria:** IHUB-WP-0021 workplan file committed; T01–T12 each have
|
Each task must have entry criteria, exit criteria, rollback notes, and the
|
||||||
entry/exit criteria; ready for execution.
|
smallest reasonable test/smoke requirement. Keep implementation slices small
|
||||||
|
enough for Codex sessions to finish without broad refactors.
|
||||||
|
|
||||||
---
|
Exit criteria: `workplans/IHUB-WP-0021-personal-dashboard-implementation.md`
|
||||||
|
exists with all tasks in `todo` state and enough detail to start implementation.
|
||||||
|
|
||||||
|
Completion note (2026-06-16): added
|
||||||
|
`workplans/IHUB-WP-0021-personal-dashboard-implementation.md` with twelve
|
||||||
|
sequenced implementation tasks covering schema, seeds, controller skeleton,
|
||||||
|
panel renderers, show/edit views, governed panel widget lifecycle, login
|
||||||
|
redirect, AutoRefresh/query hardening, tests, and manual smoke.
|
||||||
|
|
||||||
## Exit Criteria Summary
|
## Exit Criteria Summary
|
||||||
|
|
||||||
| Task | Deliverable | Status |
|
| Task | Deliverable | Status |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| T01 | `docs/research/dashboard-frameworks.md` | todo |
|
| T01 | `docs/research/personal-dashboard-current-state.md` | done |
|
||||||
| T02 | `docs/prs/dashboard-framework-prs.md` | todo |
|
| T02 | `docs/prs/personal-dashboard-prs.md` | done |
|
||||||
| T03 | `docs/fdd/dashboard-framework-fdd.md` | todo |
|
| T03 | `docs/fdd/personal-dashboard-fdd.md` | done |
|
||||||
| T04 | `workplans/IHUB-WP-0021-personal-dashboard-impl.md` | todo |
|
| T04 | `workplans/IHUB-WP-0021-personal-dashboard-implementation.md` | done |
|
||||||
|
|
||||||
## Design Principles (binding throughout)
|
## Binding Design Principles
|
||||||
|
|
||||||
- **Server-first**: every panel renders in a single round-trip. No client-side data fetching.
|
- Server-first: every panel renders on the server in the normal IHP request
|
||||||
- **Type-safe config**: `PanelConfig` is a Haskell ADT, not an opaque JSON blob at runtime.
|
lifecycle.
|
||||||
- **IHF governed**: each rendered panel is a `Widget` with a `widgetEnvelope`; interactions
|
- Integration-first: reuse current dashboard query patterns before extracting
|
||||||
are recorded; annotations can be attached.
|
shared abstractions.
|
||||||
- **Tailwind only**: no external component library. Layout via CSS Grid with inline style for
|
- Governed panels: saved panel instances have stable IHF widget identity and
|
||||||
structural properties (lessons learned from sidebar nav).
|
use `widgetEnvelope`.
|
||||||
- **Minimal JS**: AutoRefresh WebSocket for live panels; vanilla JS for any UX enhancement.
|
- Type-safe runtime config: JSONB is storage, not the unchecked runtime API.
|
||||||
No framework, no bundler beyond the existing IHP asset pipeline.
|
- Bounded queries: every panel limits rows and uses existing indexes or proposes
|
||||||
|
a specific migration.
|
||||||
|
- Minimal JS: no framework and no client-side data fetch loop.
|
||||||
|
- Tailwind only: use existing view style and responsive grid conventions.
|
||||||
|
|||||||
623
workplans/IHUB-WP-0021-personal-dashboard-implementation.md
Normal file
623
workplans/IHUB-WP-0021-personal-dashboard-implementation.md
Normal file
@@ -0,0 +1,623 @@
|
|||||||
|
---
|
||||||
|
id: IHUB-WP-0021
|
||||||
|
type: workplan
|
||||||
|
title: "Personal Dashboard Implementation"
|
||||||
|
domain: inter_hub
|
||||||
|
repo: inter-hub
|
||||||
|
status: ready
|
||||||
|
owner: codex
|
||||||
|
topic_slug: inter_hub
|
||||||
|
created: "2026-06-16"
|
||||||
|
updated: "2026-06-16"
|
||||||
|
phase: 13
|
||||||
|
depends_on: IHUB-WP-0020
|
||||||
|
related_docs:
|
||||||
|
- docs/research/personal-dashboard-current-state.md
|
||||||
|
- docs/prs/personal-dashboard-prs.md
|
||||||
|
- docs/fdd/personal-dashboard-fdd.md
|
||||||
|
state_hub_workstream_id: "79f72176-fb3f-4d59-9678-d42f5ff1e679"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Personal Dashboard Implementation
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Implement the personal dashboard framework designed in IHUB-WP-0020: a
|
||||||
|
server-rendered authenticated landing page with persisted per-user panels,
|
||||||
|
governed panel widget identity, default dashboard seeding, simple edit forms,
|
||||||
|
and six first-slice panel renderers.
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
- `docs/research/personal-dashboard-current-state.md`
|
||||||
|
- `docs/prs/personal-dashboard-prs.md`
|
||||||
|
- `docs/fdd/personal-dashboard-fdd.md`
|
||||||
|
- Existing dashboard surfaces in `Web/Controller/Hubs.hs`,
|
||||||
|
`Web/Controller/LearningDashboard.hs`, `Web/Controller/ApiDashboard.hs`,
|
||||||
|
`Web/Controller/MarketplaceDashboard.hs`, and federated governance
|
||||||
|
controllers.
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
|
||||||
|
- Keep implementation additive.
|
||||||
|
- Preserve public root/static routes.
|
||||||
|
- Do not refactor all existing dashboards.
|
||||||
|
- No client-side data fetching framework.
|
||||||
|
- No drag-and-drop layout in this workplan.
|
||||||
|
- Every saved dashboard panel must have stable `Widget` identity and render
|
||||||
|
through `widgetEnvelope`.
|
||||||
|
- Bound every panel query.
|
||||||
|
- Cast aggregate `COUNT(*)` queries when decoding as `Int`, or decode as
|
||||||
|
`Int64`.
|
||||||
|
|
||||||
|
## Tasks
|
||||||
|
|
||||||
|
### T01 - Add personal dashboard schema
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T01
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
state_hub_task_id: "bb7366a3-78ec-42d8-9f16-b7ed4979ec53"
|
||||||
|
```
|
||||||
|
|
||||||
|
Add the schema from the FDD:
|
||||||
|
|
||||||
|
- `personal_dashboards`
|
||||||
|
- `dashboard_panel_types`
|
||||||
|
- `dashboard_panels`
|
||||||
|
|
||||||
|
Implementation notes:
|
||||||
|
|
||||||
|
- Add an `Application/Migration/<timestamp>-personal-dashboard-framework.sql`
|
||||||
|
migration.
|
||||||
|
- Update `Application/Schema.sql` consistently with the migration.
|
||||||
|
- Use `panel_key`, not `key`, on `dashboard_panel_types`.
|
||||||
|
- Include `removed_at` on `dashboard_panels`.
|
||||||
|
- Include indexes and layout CHECK constraints from the FDD.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- IHUB-WP-0020 is done.
|
||||||
|
- FDD exists and is reviewed enough for implementation.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Schema files contain the three new tables and indexes.
|
||||||
|
- `rg "personal_dashboards|dashboard_panel_types|dashboard_panels" Application`
|
||||||
|
finds the expected migration/schema entries.
|
||||||
|
- No existing table or route behavior is changed.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Run `git diff --check`.
|
||||||
|
- If the IHP dev environment is available, run the repo compile/schema check
|
||||||
|
used by prior inter-hub workplans.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Before production data exists, rollback is removing the migration/schema
|
||||||
|
additions.
|
||||||
|
- After production data exists, rollback requires preserving linked `widgets`
|
||||||
|
and `interaction_events`; do not delete panel widgets casually.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T02 - Seed panel types and framework panel vocabulary
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T02
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
depends_on: T01
|
||||||
|
state_hub_task_id: "d298eab2-736d-48ed-b6d4-84afa1604de9"
|
||||||
|
```
|
||||||
|
|
||||||
|
Add idempotent seed data for:
|
||||||
|
|
||||||
|
- framework hub with slug `inter-hub` and `hub_kind = 'framework'` if absent;
|
||||||
|
- active widget type `panel` if absent;
|
||||||
|
- six first-slice `dashboard_panel_types`:
|
||||||
|
- `watched-hubs`
|
||||||
|
- `recent-interactions`
|
||||||
|
- `triage-queue`
|
||||||
|
- `recent-decisions`
|
||||||
|
- `hub-health`
|
||||||
|
- `learning-digest`
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- T01 schema exists.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Seed SQL or helper is idempotent.
|
||||||
|
- Re-running seeds does not create duplicate framework hubs, widget types, or
|
||||||
|
panel types.
|
||||||
|
- Default configs match the FDD.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Inspect seed SQL for `ON CONFLICT DO NOTHING` or equivalent idempotency.
|
||||||
|
- If DB is available, run a local seed twice and confirm row counts stay stable.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Panel type seed rows are additive. If rollback is needed before use, remove
|
||||||
|
only the new dashboard panel type rows and any framework hub created solely
|
||||||
|
for this feature.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T03 - Add controller skeleton, routes, and default dashboard helper
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T03
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
depends_on: T02
|
||||||
|
state_hub_task_id: "8a171c71-3762-46c7-88d7-10ffb87fc78a"
|
||||||
|
```
|
||||||
|
|
||||||
|
Add:
|
||||||
|
|
||||||
|
- `PersonalDashboardsController` to `Web/Types.hs`;
|
||||||
|
- `Web/Controller/PersonalDashboards.hs`;
|
||||||
|
- `Web/View/PersonalDashboards/Show.hs`;
|
||||||
|
- `Web/View/PersonalDashboards/Edit.hs` placeholder or minimal views;
|
||||||
|
- route registration in `Web/Routes.hs`;
|
||||||
|
- controller import and parser registration in `Web/FrontController.hs`;
|
||||||
|
- helper module `Application/Helper/PersonalDashboard.hs`.
|
||||||
|
|
||||||
|
Implement:
|
||||||
|
|
||||||
|
- `ensureDefaultDashboard :: User -> IO PersonalDashboard`;
|
||||||
|
- dashboard lookup scoped to current user;
|
||||||
|
- idempotent default seeding with six panel rows;
|
||||||
|
- linked `Widget` creation for each seeded panel;
|
||||||
|
- initial `WidgetVersion` creation for panel widgets.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- T01/T02 complete.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Authenticated user can hit `PersonalDashboardAction`.
|
||||||
|
- First visit creates a default dashboard with six active panels.
|
||||||
|
- A second visit does not duplicate panels.
|
||||||
|
- Controller denies unauthenticated access through `ensureIsUser`.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Compile if environment is available.
|
||||||
|
- Add or run focused helper tests if existing test harness supports it.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Remove route/controller/helper additions if skeleton must be reverted.
|
||||||
|
- Keep seeded widgets/events if any user interactions already happened.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T04 - Implement first three panel view models/renderers
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T04
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
depends_on: T03
|
||||||
|
state_hub_task_id: "012dcd2a-d3e0-48ba-966b-f4c7afa51dad"
|
||||||
|
```
|
||||||
|
|
||||||
|
Implement typed config decoding and view-model builders for:
|
||||||
|
|
||||||
|
- `watched-hubs`
|
||||||
|
- `recent-interactions`
|
||||||
|
- `triage-queue`
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
|
||||||
|
- Query from controller/helper, not from HSX views.
|
||||||
|
- Clamp configured limits.
|
||||||
|
- Apply optional hub filters.
|
||||||
|
- Render empty states.
|
||||||
|
- Include source links:
|
||||||
|
- watched hub rows link to `ShowHubAction`;
|
||||||
|
- recent interaction rows link to widget or hub context where available;
|
||||||
|
- triage rows link to `ShowRequirementCandidateAction`.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- T03 controller/helper skeleton exists.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- The three panels render in the dashboard show action.
|
||||||
|
- Invalid config falls back to defaults and records a warning in the panel view
|
||||||
|
model.
|
||||||
|
- Queries are bounded.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Compile if environment is available.
|
||||||
|
- Manual smoke with empty DB and seeded fixture data if possible.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Renderer additions are isolated to helper/view modules and can be reverted
|
||||||
|
without dropping schema.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T05 - Implement dashboard show view and responsive grid
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T05
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
depends_on: T04
|
||||||
|
state_hub_task_id: "b4c4de39-147b-45a0-954d-9bafad4aafa1"
|
||||||
|
```
|
||||||
|
|
||||||
|
Build the dashboard show view:
|
||||||
|
|
||||||
|
- title and edit link;
|
||||||
|
- responsive grid;
|
||||||
|
- panel cards using row/col/span config;
|
||||||
|
- panel title fallback to panel type label;
|
||||||
|
- warning display for invalid config or unsupported panel;
|
||||||
|
- source link area;
|
||||||
|
- `widgetEnvelope` around every panel.
|
||||||
|
|
||||||
|
Implementation notes:
|
||||||
|
|
||||||
|
- Use current Tailwind and HSX conventions.
|
||||||
|
- Add a small CSS helper in `static/app.css` only if needed for responsive
|
||||||
|
collapse.
|
||||||
|
- Keep text compact and operational.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- At least three panel view models exist.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Seeded dashboard is usable as an authenticated landing surface.
|
||||||
|
- Panels do not overlap at desktop or narrow widths.
|
||||||
|
- Panel layout persists in the order defined by `row`, `col`, and `sort_order`.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Compile if environment is available.
|
||||||
|
- Browser/manual smoke if a dev server is running.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Show view changes can be reverted independently of schema/controller work.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T06 - Implement remaining first-slice panel view models/renderers
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T06
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
depends_on: T05
|
||||||
|
state_hub_task_id: "8d0bd046-17b3-48d9-a945-8b2e9c001123"
|
||||||
|
```
|
||||||
|
|
||||||
|
Implement:
|
||||||
|
|
||||||
|
- `recent-decisions`
|
||||||
|
- `hub-health`
|
||||||
|
- `learning-digest`
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
|
||||||
|
- Recent decisions: bounded by time range and limit; link to
|
||||||
|
`ShowDecisionRecordAction`.
|
||||||
|
- Hub health: latest snapshot per hub plus active bottleneck count; use
|
||||||
|
aggregate count casting or `Int64`.
|
||||||
|
- Learning digest: recent `learning_insights` and
|
||||||
|
`institutional_knowledge_entries`; link to knowledge entries where possible.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- T05 show view can render panel view models.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- All six first-slice panels render.
|
||||||
|
- All panel queries are bounded.
|
||||||
|
- Empty states are sane for all six panels.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Compile if environment is available.
|
||||||
|
- `git diff --check`.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Each renderer should be separable so a single broken panel can be reverted
|
||||||
|
without removing the framework.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T07 - Implement edit flow
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T07
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
depends_on: T06
|
||||||
|
state_hub_task_id: "51a72b56-5c23-4baa-892f-4ab89fd8495c"
|
||||||
|
```
|
||||||
|
|
||||||
|
Implement:
|
||||||
|
|
||||||
|
- `EditPersonalDashboardAction`;
|
||||||
|
- `UpdatePersonalDashboardAction`;
|
||||||
|
- `AddDashboardPanelAction`;
|
||||||
|
- `UpdateDashboardPanelAction`;
|
||||||
|
- `RemoveDashboardPanelAction`.
|
||||||
|
|
||||||
|
Edit view capabilities:
|
||||||
|
|
||||||
|
- show existing panels in layout order;
|
||||||
|
- edit row, col, col span, row span, title, and sort order;
|
||||||
|
- edit supported config fields such as limit, time range, display mode, and
|
||||||
|
hub filter;
|
||||||
|
- add active panel type;
|
||||||
|
- remove panel.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- All six panels render on show view.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- User can modify layout and config through server-rendered forms.
|
||||||
|
- User can add a panel and remove a panel.
|
||||||
|
- Invalid layout/config re-renders edit view with an error.
|
||||||
|
- A user cannot edit another user's dashboard/panel.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Manual edit smoke.
|
||||||
|
- Focused authorization/config tests if available.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- If edit flow is unstable, keep show-only dashboard and disable edit links
|
||||||
|
until fixed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T08 - Complete governed panel widget lifecycle
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T08
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
depends_on: T07
|
||||||
|
state_hub_task_id: "ca70b76d-766f-4e6e-84f1-19943c0a347c"
|
||||||
|
```
|
||||||
|
|
||||||
|
Harden widget lifecycle behavior:
|
||||||
|
|
||||||
|
- create panel widget on panel add/seed;
|
||||||
|
- create initial `WidgetVersion` snapshot;
|
||||||
|
- create a new `WidgetVersion` snapshot when material panel config changes;
|
||||||
|
- render every panel through `widgetEnvelope`;
|
||||||
|
- preserve annotations/events when panels are removed;
|
||||||
|
- archive/deprecate linked widget on panel removal.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- Edit flow can add/remove/update panels.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Every active dashboard panel has a linked active `Widget`.
|
||||||
|
- Every linked widget has non-empty `view_context`.
|
||||||
|
- Annotate link opens the existing widget annotation flow.
|
||||||
|
- Removing a panel does not delete widget history.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Manual smoke: add panel, annotate panel, remove panel, confirm widget/event
|
||||||
|
history is not deleted.
|
||||||
|
- Inspect generated HTML for expected `data-widget-*` attributes.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Do not delete existing `widgets`, `annotations`, or `interaction_events`.
|
||||||
|
Disable dashboard rendering if needed while preserving history.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T09 - Redirect login and add navigation
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T09
|
||||||
|
status: todo
|
||||||
|
priority: medium
|
||||||
|
depends_on: T08
|
||||||
|
state_hub_task_id: "2fd1041b-9135-49e4-a9d1-e5d0b67d8fd7"
|
||||||
|
```
|
||||||
|
|
||||||
|
Update:
|
||||||
|
|
||||||
|
- `Web/Controller/Sessions.hs` to redirect successful login to
|
||||||
|
`PersonalDashboardAction`;
|
||||||
|
- `Web/FrontController.hs` sidebar to include `Dashboard`;
|
||||||
|
- any relevant public page management links only if they should point to the
|
||||||
|
dashboard rather than Hubs.
|
||||||
|
|
||||||
|
Do not change:
|
||||||
|
|
||||||
|
- public root route;
|
||||||
|
- `LandingAction`;
|
||||||
|
- capabilities/tutorial/extension guide pages;
|
||||||
|
- `HubsAction` availability.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- Dashboard show route is stable and governed panel lifecycle is complete.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Successful login lands on personal dashboard.
|
||||||
|
- Hubs remain reachable from sidebar.
|
||||||
|
- Public pages still render without login.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Manual login smoke.
|
||||||
|
- Route smoke for `/`, Hubs, dashboard, Learning, API Dashboard, Marketplace.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- If dashboard redirect fails, revert only the login redirect and keep
|
||||||
|
dashboard accessible from sidebar.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T10 - Add AutoRefresh and query hardening pass
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T10
|
||||||
|
status: todo
|
||||||
|
priority: medium
|
||||||
|
depends_on: T09
|
||||||
|
state_hub_task_id: "e19c06e7-ec95-40ca-8087-df669b575f86"
|
||||||
|
```
|
||||||
|
|
||||||
|
Wrap `PersonalDashboardAction` in `autoRefresh do` and audit all six panel
|
||||||
|
queries:
|
||||||
|
|
||||||
|
- every query is bounded;
|
||||||
|
- optional hub filter is applied before broad fetches where practical;
|
||||||
|
- aggregate counts decode safely;
|
||||||
|
- no secrets are selected or displayed;
|
||||||
|
- dashboard refresh remains acceptable with default seed data.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- Dashboard route, renderers, edit flow, and login redirect exist.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Dashboard updates using existing IHP AutoRefresh behavior.
|
||||||
|
- Query review notes are either captured in code comments or tests where useful.
|
||||||
|
- No known `COUNT(*)` as `Int` decode hazard remains in dashboard code.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Compile if environment is available.
|
||||||
|
- Manual refresh smoke by adding an interaction/candidate and observing the
|
||||||
|
dashboard update, when a dev DB is available.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Remove `autoRefresh` wrapper if it causes unacceptable behavior; keep static
|
||||||
|
dashboard route.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T11 - Add focused tests
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T11
|
||||||
|
status: todo
|
||||||
|
priority: medium
|
||||||
|
depends_on: T10
|
||||||
|
state_hub_task_id: "32b4f55e-ede6-4830-a171-b0785afe88e1"
|
||||||
|
```
|
||||||
|
|
||||||
|
Add focused tests where the current harness supports them:
|
||||||
|
|
||||||
|
- default dashboard seeding is idempotent;
|
||||||
|
- seeded dashboard has six active panels;
|
||||||
|
- each active panel has linked widget identity;
|
||||||
|
- config decoder clamps limits and rejects unknown values safely;
|
||||||
|
- remove action soft-removes panel and archives widget;
|
||||||
|
- users cannot edit another user's dashboard;
|
||||||
|
- aggregate counts in dashboard helpers decode safely.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- T10 implementation is stable enough to test.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Relevant test files exist or a documented reason explains why the current
|
||||||
|
harness cannot cover a case.
|
||||||
|
- Tests pass where runnable in the local environment.
|
||||||
|
|
||||||
|
Verification:
|
||||||
|
|
||||||
|
- Run available test command.
|
||||||
|
- If unavailable, record exact blocker in this workplan before closing T11.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- Do not weaken production behavior to satisfy a brittle test; adjust the test
|
||||||
|
to match the intended FDD contract.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### T12 - Manual smoke and closeout
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: IHUB-WP-0021-T12
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
depends_on: T11
|
||||||
|
state_hub_task_id: "8c6648ae-d33e-48f6-9d56-ee557f367d80"
|
||||||
|
```
|
||||||
|
|
||||||
|
Run a manual smoke pass:
|
||||||
|
|
||||||
|
1. Log in as an existing admin user.
|
||||||
|
2. Confirm redirect lands on personal dashboard.
|
||||||
|
3. Confirm all six seeded panels render.
|
||||||
|
4. Click source links from watched hubs, triage queue, and learning digest.
|
||||||
|
5. Open Annotate for one panel.
|
||||||
|
6. Edit layout and save.
|
||||||
|
7. Sign out/in and confirm layout persists.
|
||||||
|
8. Add and remove a panel.
|
||||||
|
9. Confirm Hubs, Hub show, Ops Review, Federation, Learning, API Dashboard,
|
||||||
|
Hub Registry, and Marketplace still load.
|
||||||
|
10. Run `git diff --check`.
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
|
||||||
|
- T01 through T11 complete or have explicit accepted caveats.
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
|
||||||
|
- Smoke evidence is recorded in this workplan or a short docs/evidence note.
|
||||||
|
- WP-0021 tasks reflect final status.
|
||||||
|
- State Hub progress note is logged.
|
||||||
|
- Operator is reminded to run `make fix-consistency REPO=inter-hub` from
|
||||||
|
`~/state-hub` after workplan/status changes.
|
||||||
|
|
||||||
|
Rollback notes:
|
||||||
|
|
||||||
|
- If smoke fails after login redirect, first rollback is reverting the login
|
||||||
|
redirect while keeping dashboard route available for debugging.
|
||||||
|
|
||||||
|
## Workplan Exit Criteria
|
||||||
|
|
||||||
|
- Personal dashboard schema, seeds, controller, views, helper, and route are
|
||||||
|
implemented.
|
||||||
|
- Successful login reaches the personal dashboard.
|
||||||
|
- Default dashboard seeding is idempotent.
|
||||||
|
- Six first-slice panels render with bounded queries.
|
||||||
|
- Panel edit flow works.
|
||||||
|
- Every panel has governed widget identity.
|
||||||
|
- Existing source dashboards remain functional.
|
||||||
|
- Checks/smoke evidence is recorded.
|
||||||
Reference in New Issue
Block a user