Build a real-time rewards visualization module consuming guildpass-core reward/streak data

[Lakes41]

Difficulty: Expert
Type: feature

Background
The README lists "rewards visualization" among the intentionally deferred features, while guildpass-core's data model already includes badges (placeholder) and outbox event types that a reward/streak engine would emit if implemented there.

Problem
Even once guildpass-core can compute rewards/streaks (a related deferred capability there), this frontend has no visualization surface for members to see their own reward history/streaks or for admins to see community-wide reward distribution — and no defined contract for how this frontend would consume that data live.

Expected outcome
A member-facing "My Rewards" view shows streak status and reward/badge history with live updates as new rewards are earned, and an admin-facing "Community Rewards" view shows aggregate distribution, both built against a clearly documented (and mock-implemented) API contract this frontend expects from guildpass-core.

Suggested implementation

• Document the expected guildpass-core endpoints (e.g., GET /v1/members/:address/rewards, GET /v1/community/rewards/summary) in a new docs/rewards-contract.md, aligned with the outbox event types already documented there if a reward engine is later built to emit them.
• Implement full mock support in lib/api/mock.ts: seeded streak/reward history for members, and aggregate summary data for the admin view.
• Build the member "My Rewards" page (streak visualization, badge/reward timeline) and the admin "Community Rewards" page (distribution chart, top contributors).
• For "live updates," implement a polling-based refresh (React Query's refetchInterval) as the practical, incrementally-adoptable approach, documenting how a future push-based mechanism (SSE/WebSockets) could replace it once guildpass-core supports it.
• Ensure the module is additive and doesn't assume guildpass-core's reward engine exists yet — live-mode calls should degrade gracefully (clear "not yet available" state) if the backend doesn't implement the documented contract.

Acceptance criteria

• Both member and admin reward views fully function in mock mode
• API contract documented clearly enough for independent backend implementation
• Live mode degrades gracefully (no hard crash) if the backend doesn't yet support the contract
• Data refreshes periodically without requiring a manual page reload

Likely affected files/directories

• app/rewards/ (new, member + admin views)
• lib/api/mock.ts, lib/api/live.ts, lib/api/types.ts
• docs/rewards-contract.md (new)

[julianvillalba688]

Motivation & Relevant Experience:
I have extensive experience building robust, data-heavy frontend modules in React/Next.js, specifically leveraging React Query for real-time state synchronization and polling. I am highly comfortable with contract-first API design, building comprehensive mock layers for parallel development, and creating complex data visualizations (charts, timelines). I specialize in defensive frontend architectures, ensuring that UIs degrade gracefully rather than crashing when expected backend endpoints are unavailable or still in development.

Proposed Approach:

API Contract & Mock Implementation: I will start by drafting docs/rewards-contract.md to define strict, backend-agnostic schemas for GET /v1/members/:address/rewards and GET /v1/community/rewards/summary. I will then populate lib/api/mock.ts with rich seeded data (streaks, badge histories, and aggregate metrics) to fuel UI development.

Resilient Data Fetching: I will implement the live API wrappers in lib/api/live.ts using React Query. I'll configure refetchInterval for near-real-time polling and implement strict error handling. If the backend returns a 404/501 (meaning the reward engine isn't deployed yet), the UI will gracefully fallback to a polished "Rewards engine not yet available" empty state.

UI/UX Construction (app/rewards/):

Member View: I will build a visual streak tracker and a chronological timeline component for earned badges.

Admin View: I will implement aggregated distribution charts and a top contributors list to display community-wide metrics.

Future-Proofing: I will document the upgrade path within the code and documentation, detailing exactly how the React Query polling mechanism can be seamlessly replaced with SSE or WebSockets once guildpass-core supports push events.

I can deliver this module fully tested and matching the acceptance criteria within 24 hours.

[grantfox-oss]

🦊 GrantFox — @julianvillalba688 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.