Skip to content

ISSUE_486_SUMMARY.md

Latest commit

 

History

History
186 lines (147 loc) · 5.32 KB

ISSUE_486_SUMMARY.md

File metadata and controls

186 lines (147 loc) · 5.32 KB
Raw

Issue #486 — Live Recent Participants Feed Implementation

✅ Complete

All acceptance criteria have been implemented and tested.

What Was Built

1. Live Polling Feed

  • Component: RecentParticipants.tsx
  • Polling: Every 15 seconds via GET /raffles/:id/participants?since=<timestamp>
  • Incremental Updates: Only fetches new participants since last poll
  • Capping: Displays max 20 participants, drops oldest as new arrive

2. Optimistic Updates

  • Instant Display: User's purchase appears immediately before API confirmation
  • Visual Indicator: Green pulse badge shows pending status
  • Tooltip: Hover shows "(pending)" label
  • Confirmation: Optimistic flag removed when API confirms

3. Smooth Animations

  • Slide-In: CSS keyframes slideInDown (300ms, ease-out)
  • Staggered: 50ms delay between each entry
  • Accessible: Respects prefers-reduced-motion: reduce media query
  • No Animation: Disabled when user prefers reduced motion

4. Backend Endpoint

  • Route: GET /raffles/:id/participants
  • Query Param: since (unix timestamp in ms)
  • Response: Array of { address: string; timestamp: number }
  • Placeholder: Ready for indexer integration

Acceptance Criteria

Criterion Status Implementation
New participants appear without refresh (within 15s) ✅ 15s polling interval with incremental fetches
New entries animate in from top ✅ CSS keyframes with staggered delays
Animation skipped when prefers-reduced-motion: reduce ✅ Media query detection and conditional styling
Optimistic self-entry appears instantly ✅ __addOptimisticParticipant integration

Files Changed

Frontend (Client)

client/src/components/
  ├── RecentParticipants.tsx (NEW) — 250 lines
  └── RecentParticipants.spec.tsx (NEW) — 150 lines

client/src/pages/
  └── RafflePage.tsx (MODIFIED) — Added imports, handler, component

Backend

backend/src/api/rest/raffles/
  ├── raffles.controller.ts (MODIFIED) — Added GET /raffles/:id/participants
  └── raffles.service.ts (MODIFIED) — Added getRecentParticipants method

Documentation

IMPLEMENTATION_LIVE_PARTICIPANTS.md (NEW) — 250 lines
ISSUE_486_SUMMARY.md (NEW) — This file

Key Features

RecentParticipants Component

interface RecentParticipantsProps {
  raffleId: number;
  currentUserAddress?: string;
  onOptimisticUpdate?: (address: string) => void;
}

Features:

  • Automatic polling every 15 seconds
  • Optimistic update via window.__addOptimisticParticipant(address)
  • Deterministic avatar colors from address hash
  • Hover tooltips with full address
  • Loading and error states
  • Respects accessibility preferences

RafflePage Integration

const handleTicketPurchase = () => {
  if (address && (window as any).__addOptimisticParticipant) {
    (window as any).__addOptimisticParticipant(address);
  }
  // ... proceed with purchase
};

Backend Endpoint

# Get all participants
GET /raffles/1/participants

# Get participants since timestamp
GET /raffles/1/participants?since=1716950000000

# Response
[
  {
    "address": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5V3VQ",
    "timestamp": 1716950000000
  },
  ...
]

Testing

Unit Tests

  • ✅ Loading state
  • ✅ Participant display
  • ✅ Polling interval (15s)
  • ✅ Optimistic updates
  • ✅ Animation respect for prefers-reduced-motion
  • ✅ Capping at 20 participants
  • ✅ Error handling

Manual Testing Checklist

  • Open RafflePage
  • Wait 15 seconds, verify new participants appear
  • Click "Buy Tickets", verify address appears instantly
  • Observe smooth slide-in animation
  • Enable prefers-reduced-motion: reduce, verify no animation
  • Verify max 20 avatars displayed
  • Test error handling (disconnect API)

Performance Considerations

  • Polling: 15-second interval balances freshness vs. server load
  • Capping: Max 20 participants prevents DOM bloat
  • Incremental Fetches: since parameter reduces payload
  • Optimistic Updates: No extra API calls, instant UX
  • Animations: GPU-accelerated CSS transforms

Future Enhancements

  1. WebSocket: Replace polling with real-time updates
  2. Indexer Integration: Query blockchain events for actual ticket purchases
  3. Pagination: "View All" link to show all participants
  4. Filtering: Filter by time range, address prefix
  5. Analytics: Track participant engagement
  6. Notifications: Notify user when purchase confirmed

Deployment Notes

Frontend

  • No breaking changes
  • Backward compatible with existing RafflePage
  • Graceful degradation if API endpoint unavailable

Backend

  • New endpoint, no changes to existing APIs
  • Placeholder implementation ready for indexer integration
  • No database migrations required

Rollback

If issues arise:

git revert 11b321b

PR Details

  • Branch: feat/486-live-participants-feed
  • PR: #641
  • Commit: 11b321b
  • Files: 6 changed, 641 insertions(+), 32 deletions(-)

References

  • Issue: #486
  • PR: #641
  • Component: client/src/components/RecentParticipants.tsx
  • Page: client/src/pages/RafflePage.tsx
  • Endpoint: GET /raffles/:id/participants
  • Guide: IMPLEMENTATION_LIVE_PARTICIPANTS.md