Skip to main content

Developer-ready checklist for Module 8: Insights & Compliance Dashboards. It mirrors prior modules with acceptance criteria, edge cases, security, observability, and DoD so the team can implement and verify step-by-step.

8. Insights & Compliance Dashboards — Developer Checklist

0) Foundations (blockers if incomplete)​

Feature flags: insights.home, insights.chemical, insights.training, insights.plan, insights.ai_pro, insights.exports, insights.scheduling. DB & views: materialized views / SQL views for KPIs vw_insights_home, vw_insights_chemicals, vw_insights_training, vw_insights_plans, vw_insights_scores, insight_snapshots, report_jobs. Pipelines: nightly ETL/cron workers (Sentinel) to refresh materialized views + compute Pro AI scores. APIs: REST/GraphQL endpoints for each widget with pagination & filters; server-side tenant scoping. Assets: chart component library, PDF/CSV/XLSX exporters, template for monthly digest. Localization: EN/ES strings for dashboard widgets, exports, and emails.

8.1 Purpose & Structure (analytics hooks)​

Track events: insights.view, insights.filter_change, insights.export, insights.schedule_created, insights.ai_explanation_opened. Role-based visibility (Admin full, Manager site-level, Employee personal). Snapshot writer creates daily insight_snapshots for trend lines. Acceptance: Each dashboard view emits analytics; metrics reflect user’s role and tenant scope.

8.2 Home / Compliance Dashboard​

8.2.1 Starter​

Checklist widget only with current plan version, SDS count, trainings completed. Readiness Bar = avg(SDS coverage %, plan validity %, training completion %). Manual email notifications only. Acceptance: Readiness matches formula; values scoped to company/site per role.

8.2.2 Standard​

Adds rule-based alerts: expired SDS, overdue training, stale plan (>365d). Drill-down to filtered lists (Chemicals/Training/Plans). Email + in-app notifications; time-based reminders. Acceptance: Clicking alerts opens the correct filtered list; reminders queue successfully.

8.2.3 Pro​

AI Compliance Score and Next Audit Risk panel. Monthly summary report generation (PDF/CSV/XLSX). Cross-company analytics (multi-site aggregation) + Slack/Webhook. Acceptance: Scores present; scheduled monthly report delivered; webhook sent.

8.3 Chemical Dashboard (Powered by AI Agent)​

8.3.1 Overview Panel​

Location selector; show HazCom Plan status banner. Overview cards: Distinct Hazard Types, Hazard Classes Count, Total Hazardous Products. Acceptance: Counts match inventory + SDS parsing results.

8.3.2 Key Metrics​

Total SDS, SDS Coverage %, Employees Trained %, Pending Trainings. Acceptance: KPI math verified against underlying tables.

8.3.3 GHS Pictogram Overview​

Tally by pictogram; red-diamond visuals. AI hints for under-represented or anomalous patterns. Acceptance: Counts align with Section 2 data; hints generated only when thresholds exceeded.

8.3.4 Charts & Analytics​

Hazard Distribution pie (Health/Physical/Environmental). Bar: GHS categories 1–5; Stacked: inventory vs product count by hazard class. Pro: cross-site comparison (hazard density per site). Acceptance: Charts update with filters (site, date range) within 300ms p95.

8.3.5 AI Insights (Pro)​

Detect imbalances (e.g., high flammables vs low PPE training). Predict next SDS likely to update; suggest re-training triggers. Acceptance: Each suggestion includes short explanation + linked evidence.

8.3.6 Exports​

PDF snapshot, CSV/XLSX data dumps, API endpoint for external BI. Acceptance: Exported figures match on-screen metrics; API enforces tenant scope.

8.4 Training Dashboard​

8.4.1 Metrics​

Completion rate by site/department; overdue/expiring trainings; average quiz score; top missed questions. Acceptance: Counts reconcile with Training module results.

8.4.2 Visualizations​

Completion donut, overdue heatmap by role, retraining timeline. Acceptance: Heatmap accurately reflects overdue by role/site.

8.4.3 AI Insights (Pro)​

Risk prediction: departments at risk (e.g., “Mechanical shop overdue >60 days”). Suggested retraining for hazard-intense sites. Acceptance: Risk cards clickable → pre-filtered assignment list.

8.5 HazCom Plan Dashboard​

8.5.1 Metrics​

Active vs expired; days since last approval; version history timeline; approver summary. Acceptance: Last approval date and status match Plan module.

8.5.2 Alerts​

“Plan Overdue” (>365 days); “Pending Approval” flags. Acceptance: Alerts clear when condition resolves.

8.5.3 AI Layer (Pro)​

Flag sections unchanged >12 months. Suggest revise for sections affected by new hazards since last version. Acceptance: Suggestions cite the hazard change and impacted section.

8.6 AI Insights Dashboard (Pro Only)​

8.6.1 AI Anomaly Detection​

Missing SDS, new hazard classes, rapid turnover detection. Acceptance: Only fires when thresholds crossed; includes remediation steps.

8.6.2 Predictive Risk Analytics​

“Next Inspection Risk” score per site (0–100); readiness forecast. Acceptance: Scores stable day-to-day; major events shift scores predictably.

8.6.3 Compliance Score & Correlation​

Health Index = 0.4SDS + 0.3Training + 0.2Plan freshness + 0.1Label activity. Correlation panel: how factors drive score changes. Acceptance: Score matches formula; correlation panel lists top drivers.

8.6.4 Automated Summaries​

Monthly “Compliance Digest” PDF to Coordinator; optional webhook to BI tools. Acceptance: Digest includes 30-day charts + key deltas; delivery logged.

8.7 Reports & Exports​

8.7.1 Report Types​

Starter: PDF; Standard: PDF+CSV; Pro: PDF+CSV+XLSX+API. Acceptance: Tier gates enforced on UI and API.

8.7.2 Scheduling​

Starter manual; Standard recurring schedule; Pro AI-scheduled (auto cadence by activity). Acceptance: Schedules persist; jobs run on time; pause/resume works.

8.7.3 Export Content​

Company summary, site chemical analytics, training records, plan versions. Acceptance: Content matches dashboard filters/time range.

Security Checklist (must-pass)​

Tenant isolation: all queries filter by company_id (+ site_id for Manager); enforced via RLS or API layer. Least privilege: role-based widget visibility; Employee sees only personal training status. PII minimization: exports redacted for Employee-level details unless Admin/Manager. Rate limiting: on exports and AI explanation endpoints. Snapshot integrity: signed snapshot IDs; immutable after write; backfilled corrections logged. Webhook security: HMAC-signed payloads; retry with backoff. Model governance (Pro AI): prompt inputs exclude sensitive PII; store minimal prompts with retention policy.

QA Test Matrix​

Happy Paths Admin views Home → sees Readiness Bar and rule-based alerts; drill-down works. Manager selects site → Chemical dashboard updates KPIs, charts, pictogram counts. Training dashboard: completion donut reflects assignments; export CSV matches counts. Plan dashboard: overdue plan flagged; approving in Module 6 clears alert. Pro: AI Insights shows Compliance Score + Monthly Digest generated and delivered. Edge Cases No SDS at site → Chemical charts show empty states; hints suggest actions. Large inventory (10k items) → charts paginate/aggregate; response < 800ms p95 with caching. Conflicting data (duplicate SDS) → dashboard warns and links to fix in Inventory. Time range with no data → exports generated with headers + “no records” rows. Permission test: Employee cannot see company roll-up; Manager cannot view other sites. Cross-Platform Responsive layouts; charts readable on tablet. High-contrast/accessible legends and alt text for pictograms. Performance Widget API p95 < 300ms (cached), < 700ms (fresh). Export generation: PDF < 5s, CSV/XLSX stream-start < 1s. Nightly AI job completes within window; partial retry on failure.

Observability / Alerts​

Dashboards: widget latency, cache hit rate, export counts/failures, AI score job health. Alerts: export failure rate spike, ETL refresh failures, stale snapshots (>48h), webhook delivery failures.

Deliverables (Definition of Done)​

Figma: Home, Chemical, Training, Plan, AI dashboards; empty/error states; export/schedule modals. OpenAPI/GraphQL: /insights/home, /insights/chemicals, /insights/training, /insights/plans, /insights/ai, /insights/exports, /insights/schedules. Localization: EN/ES UI strings; email templates for monthly digest & alerts. E2E tests: happy paths + edge cases above (Cypress/Playwright). Admin tools: rebuild materialized views; backfill snapshots; resend monthly digest; configure AI thresholds per site. Rollback plan: disable insights.ai_pro to fall back to Standard dashboards; exports continue to function.

If you’d like, I can convert this into a Jira/Linear task breakdown (epic → stories → subtasks) or a CSV checklist your team can check off per sprint.