Integrate All Admin Panels into Dashboard Screen

epic-admin-portal-dashboard-ui-task-015 — Compose the complete AdminDashboardScreen by integrating the KPI grid, ActivityLogViewer, CertificationStatusPanel, AdminExportPanel, and RoleAssignmentPanel trigger into a unified tab or section layout. Implement navigation between panels using a tab bar or drawer. Ensure that the org hierarchy scope from the OrgHierarchyNavigator propagates to all panels via the shared AdminPortalBloc.

critical priority high complexity frontend pending fullstack developer Tier 4

Acceptance Criteria

AdminDashboardScreen is the single root widget that composes all governance panels within one BlocProvider for AdminPortalBloc

Tab bar or navigation drawer exposes at minimum: Overview (KPI grid), Activity Log, Certifications, Export, and Role Assignment sections

Switching tabs preserves each panel's scroll position and loaded data (StatefulShellRoute or IndexedStack pattern)

The OrgHierarchyNavigator is visible on all tabs and its selected scope is immediately reflected in every panel without requiring a manual refresh

KPI grid occupies the Overview tab and displays metrics scoped to the currently selected org node

ActivityLogViewer, CertificationStatusPanel, AdminExportPanel, and RoleAssignmentPanel trigger are each hosted in their dedicated tabs

Deep-link navigation to a specific tab (e.g., from a notification) is supported via named routes or shell route parameters

AdminDashboardScreen handles the BLoC loading state with a full-screen skeleton rather than per-panel spinners on initial load

All panels share a single AdminPortalBloc instance — no duplicate blocs or independent data fetches per panel

Screen is accessible: tab labels are announced by screen readers, focus management works correctly when switching tabs

Technical Requirements

frameworks

Flutter

BLoC (flutter_bloc)

go_router (StatefulShellRoute)

flutter_test

apis

All admin service APIs consumed by integrated panels

data models

AdminPortalState

OrgScopeNode

DashboardTab (enum)

performance requirements

Initial dashboard load must display the KPI tab skeleton within 200ms of navigation

Tab switches must complete without jank — use IndexedStack or StatefulShellRoute to avoid widget rebuilds

AdminPortalBloc must batch initial data fetches to avoid sequential waterfall requests on screen open

security requirements

AdminDashboardScreen route must be guarded by an admin role check in the router redirect; non-admins are redirected to a no-access screen

Each panel must not independently re-authenticate; all API calls flow through the shared BLoC which holds the authenticated Supabase client

Role Assignment section must only be visible to users with the 'org_admin' or higher role; conditionally render or hide based on BLoC role state

ui components

AdminDashboardScreen

AdminTabBar (top or side depending on viewport)

AdminDashboardSkeleton (initial full-screen loading state)

OrgHierarchyNavigator (persistent across all tabs)

KpiOverviewTab

ActivityLogTab

CertificationsTab

ExportTab

RoleAssignmentTab

Execution Context

Execution Tier

Tier 4

Tier 4 - 323 tasks

Can start after Tier 3 completes

View Full Execution Plan

Implementation Notes

Wrap the entire AdminDashboardScreen in a single BlocProvider at the route level so all child panels receive the same bloc instance. Use BlocListener at the screen level for cross-cutting concerns like showing error snackbars. Use IndexedStack for tab content if tab state preservation is critical, noting it keeps all panel widgets alive; alternatively use StatefulShellRoute branches in go_router which achieves the same with better route integration. Dispatch a DashboardInitialised event in initState or via an initBloc builder so all panels begin fetching data in one coordinated batch.

The OrgHierarchyNavigator should be placed above the tab content in the widget tree but inside the BlocProvider so it reads and writes scope to the same bloc instance. Keep AdminDashboardScreen itself thin — it orchestrates layout and routing but contains no business logic.

Testing Requirements

Write widget integration tests using flutter_test: (1) all panels render without errors when provided a populated AdminPortalBloc state; (2) switching tabs preserves scroll position of the previous tab; (3) org scope change triggers data refresh in all visible panels; (4) deep-link to Certifications tab renders the correct panel; (5) non-admin user is redirected away from the screen. Use a MockAdminPortalBloc with pre-seeded states for each test scenario. Add a smoke golden test for the full dashboard layout at both mobile (375px) and tablet (768px) widths to catch layout regressions.

Component

Admin Dashboard Screen

ui high

Dependencies (4)

Implement the ActivityLogViewer widget as a scrollable, filterable list of activities across all org chapters within the selected scope. Include filter controls for date range, activity type, and chapter. Each list item must show key metadata and provide a navigation link to the originating activity registration detail screen. Support paginated loading via the AdminPortalBloc. epic-admin-portal-dashboard-ui-task-008 Implement the AdminExportPanel widget that allows admins to configure and trigger CSV/Excel exports. The panel must include scope selector (org/chapter), date range picker, format selector (CSV/Excel), a trigger button, a progress indicator for in-flight export jobs, and a download link once the export completes. Consume export job progress from the AdminPortalBloc. epic-admin-portal-dashboard-ui-task-010 Implement the AdminDashboardScreen that renders the KPI stat widget grid using AdminKpiStatWidget tiles. The screen must consume the AdminPortalBloc for stat data, support drill-down navigation from each widget, adapt responsively for Flutter Web wide-screen layouts and mobile embedding, and integrate the OrgHierarchyNavigator for scope selection at the top. epic-admin-portal-dashboard-ui-task-004 Implement the CertificationStatusPanel widget that groups peer mentors with expiring or expired certifications by chapter within the selected org scope. Each group must show mentor name, certification expiry date, and current status badge. Include a 'Send Reminder' action button per mentor or per chapter group that calls the admin notification dispatcher. Support empty state and loading indicators. epic-admin-portal-dashboard-ui-task-012

Epic Risks (3)

high impact medium prob technical

If org node selection in AdminStateBLoC does not correctly propagate to all dependent data streams (statistics, activity log, user list, certification panel), some panels may show data from the previously selected org scope, creating a confusing and potentially dangerous mixed-scope view.

Mitigation & Contingency

Mitigation: Model org node selection as a single source of truth in AdminStateBLoC. All downstream providers derive their query parameters from this single stream via Riverpod's watch pattern. Write integration tests that verify every data stream emits a reload event when the selected node changes.

Contingency: If scope propagation bugs are detected in QA, add an explicit full-state reset on org node change (clear all cached data and refetch from scratch) as a safe but less efficient fallback until the targeted propagation is fixed.

medium impact medium prob technical

The Admin Dashboard Screen must adapt its layout for Flutter Web (wider viewports, mouse interaction, larger grid) and mobile embedding. Flutter Web responsive layout support has historically required non-trivial workarounds, and the adaptive grid may introduce significant additional development time.

Mitigation & Contingency

Mitigation: Define breakpoints and grid behaviour in the design system before implementation. Use LayoutBuilder with explicit breakpoint constants rather than MediaQuery scattered across widgets. Prototype the web layout with a skeleton screen before implementing live data binding.

Contingency: If web layout proves intractable within sprint, deliver a mobile-first layout for all platforms initially and track a dedicated web-optimisation task for the next sprint.

high impact low prob security

A bug in the Role Assignment Panel's permission scope validation could allow an org_admin to assign roles beyond their authority (e.g., assigning super_admin to a user), representing a serious privilege escalation vulnerability.

Mitigation & Contingency

Mitigation: Enforce role assignment scope on both the client (disable unavailable roles in the panel UI) and the server (UserManagementService validates the target role is within the admin's permitted scope before persisting). Write security-focused tests that attempt out-of-scope role assignments and assert rejection.

Contingency: If an escalation vulnerability is discovered, immediately disable the role assignment panel via feature flag, revoke any incorrectly assigned roles, and deploy a server-side fix before re-enabling.

Quick Links

All Tasks Execution Plan