[Feature] Add a real-time pool health score widget on the dashboard with trend indicators and actionable suggestions

[Sendi0011]

Getting Started

1. Fork the repository: https://github.com/JointSave-org/Joint_Save
2. Clone your fork:

git clone https://github.com/<your-username>/Joint_Save.git
cd Joint_Save

3. Create a new branch:

git checkout -b feat/pool-health-score-widget

---

Overview

Pool members currently have no quick way to assess the health of their pools without navigating to each pool's detail page. There is no aggregated view that shows which pools need attention (approaching deadlines, missing deposits, low TVL trend) and which are healthy.

This issue adds a pool health score widget to the dashboard that computes and displays a health score for each of the user's pools, with trend indicators, actionable suggestions, and drill-down links.

Requirements

Health Score Calculation

• New utility: frontend/lib/pool-health.ts
  • calculatePoolHealth(pool, members, activities) → PoolHealthScore:
    • score: number (0-100)
    • grade: 'A' | 'B' | 'C' | 'D' | 'F'
    • factors: depositCompliance, memberActivity, tvlTrend, deadlineProximity, disputeCount
    • trend: 'improving' | 'stable' | 'declining'
    • suggestions: string[]
  • Grade mapping: A (90-100), B (70-89), C (50-69), D (30-49), F (0-29)

Dashboard Widget

• New component: frontend/components/dashboard/pool-health-widget.tsx

  • Horizontal scrollable row of pool health cards
  • Each card: pool name, type badge, circular progress ring, letter grade, trend arrow, top suggestion
  • "Overall Health" summary card showing average score
  • "View Details" link to pool detail page

• New component: frontend/components/dashboard/health-suggestion-list.tsx

  • Expandable section listing actionable suggestions across all pools
  • Sorted by urgency (declining pools first)

Suggestion Engine Rules

• depositCompliance < 80%: "X members haven't deposited for the current round"
• deadlineProximity < 30%: "Deposit deadline is approaching in X days"
• trend === 'declining': "TVL has decreased over the last 7 days"
• memberActivity < 50%: "X members have been inactive for 30+ days"
• 0 activity in 14 days: "No activity in 2 weeks"
• Member count < 3: "Pool has very few members"

Performance

• Scores computed client-side to avoid additional API calls
• Cache computed scores for 5 minutes
• For users with >20 pools, show top 5 and a "View All" link

Acceptance Criteria

• Health score widget renders at the top of My Groups tab
• Each pool card shows score, grade, trend, and top suggestion
• Overall health summary shows average score across all pools
• Health score calculation uses all specified factors
• Grade mapping (A-F) is correct
• Trend indicator correctly shows improving/stable/declining
• Suggestions are actionable and specific to each pool's issues
• Health suggestion list expands below the cards
• Scores are cached and re-computed every 5 minutes
• Widget degrades gracefully when pool data is loading
• Mobile: health cards scroll horizontally
• Widget is hidden when user has no pools

[benzy018]

Hello Maintainer! 👋 I’d like to work on this issue. I can deliver it according to the requirements and submit a PR within 2 days. Thank you! 🚀

[grantfox-oss]

🦊 GrantFox — @benzy018 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #224)
2. Your PR will be reviewed by the JointSave-org maintainers

Good luck! Track your progress on GrantFox.