inter-hub/docs/prs/personal-dashboard-prs.md

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.