ocean-cleanup/ATTENDEE_TRACKING_FEATURE.md

Event Attendee Tracking & Contributions Feature

Overview

Added comprehensive attendee tracking and individual contribution management for cleanup events. Organizers can now mark who attended, track individual litter collection amounts, and add notes about each volunteer's contribution.

Database Changes

Schema Updates

• Added litter_collected (DECIMAL 10,2) to event_registrations table
• Added contribution_note (TEXT) to event_registrations table
• Migration: 20251118183315_add_attendee_contributions

New Type Definitions

interface EventAttendee {
  id: string;
  userId: string;
  eventId: string;
  registeredAt: Date;
  attended: boolean;
  litterCollected?: number;
  contributionNote?: string;
  user: {
    id: string;
    username: string;
    firstName?: string;
    lastName?: string;
    avatarUrl?: string;
  };
}

Backend API Endpoints

New Endpoints

1. GET /api/events/:id/attendees - Get all attendees for an event
2. PATCH /api/events/:id/attendees/:attendeeId - Update single attendee status
3. POST /api/events/:id/attendees/bulk - Bulk update attendees

Updated Endpoints

• POST /api/events/:id/complete - Now accepts optional attendees array

Frontend Components

1. AttendeeManagement Component

Location: src/components/event/AttendeeManagement.tsx

Features:

• View all registered attendees
• Mark who attended with checkboxes
• Track individual litter collection (kg)
• Add contribution notes for each volunteer
• Real-time summary stats (registered, attended, total litter)
• Bulk save changes

Usage:

<AttendeeManagement
  eventId={eventId}
  onClose={handleClose}
  onSave={handleSave}
  isLoading={isLoading}
/>

2. CompletedEventDetails Component

Location: src/components/event/CompletedEventDetails.tsx

Features:

• Display event completion summary
• Show top contributors with rankings (🥇🥈🥉)
• List all attendees with avatars
• Display event photos in grid
• Expandable contributor list

Usage:

<CompletedEventDetails
  eventId={event.id}
  totalLitterCollected={event.litterCollected}
  photos={event.photos}
/>

3. Updated EventCompletionForm

Location: src/components/event/EventCompletionForm.tsx

New Flow:

1. Step 1: Manage Attendees - Mark attendance and individual contributions
2. Step 2: Event Summary - Add photos and confirm total litter collected
3. Auto-calculates total litter from individual contributions

Event Completion Workflow

For Organizers:

1. After Event Date Passes:

   • "Complete Event" button appears in event detail modal

2. Step 1 - Manage Attendees:

   • View all registered participants
   • Check boxes for who actually attended
   • Enter litter collected by each volunteer (kg)
   • Add optional notes about contributions
   • See real-time totals

3. Step 2 - Event Summary:

   • Total litter auto-calculated from attendees
   • Upload event photos (max 5)
   • Review and submit

4. After Completion:

   • Event status changes to "completed"
   • Attendee data saved
   • Event marked with completion badge

For Viewing Completed Events:

Displays:

• Total litter collected
• Number of volunteers
• Top contributors with rankings
• All attendees list
• Event photos
• Individual contribution notes

Service Layer Updates

Backend (server/src/services/eventService.ts)

• getEventAttendees(eventId) - Fetch attendees with user details
• updateAttendeeStatus(eventId, userId, data) - Update single attendee
• bulkUpdateAttendees(eventId, attendees) - Bulk update multiple attendees

Frontend (src/services/eventService.ts)

• Updated completeEvent() to handle attendee data
• Automatically calls bulk update before completing event

UI/UX Features

Attendee Management Table

• Sortable by name
• Avatar display
• Inline editing
• Real-time validation
• Change tracking (shows count of unsaved changes)

Completed Event Display

• Green success badge
• Medal icons for top 3 contributors
• Expandable lists
• Photo gallery with click-to-enlarge
• Responsive grid layouts

Summary Statistics

• Registered count
• Attended count
• Total litter collected
• Individual contributions

Data Flow

1. Organizer clicks "Complete Event"
   ↓
2. AttendeeManagement loads registered users
   ↓
3. Organizer marks attendance & contributions
   ↓
4. Data saved via bulk update API
   ↓
5. EventCompletionForm shows summary
   ↓
6. Organizer adds photos & confirms
   ↓
7. Event marked complete
   ↓
8. CompletedEventDetails displays results

Validation

• Litter amounts must be positive numbers
• Attended status is boolean
• Contribution notes are optional text
• Total litter calculated from individual contributions

Future Enhancements

Potential additions:

• Export attendee data to CSV
• Send completion certificates to volunteers
• Impact score updates based on contributions
• Leaderboards for top volunteers
• Photo uploads per attendee
• Time tracking for volunteer hours

Testing

To test the feature:

1. Create an event with a past date
2. Register multiple users
3. As organizer, click "Complete Event"
4. Mark attendees and add contributions
5. Upload photos and complete
6. View completed event details

Migration Instructions

If deploying to a new environment:

1. Run npx prisma migrate deploy in server directory
2. Or manually run: npx tsx src/scripts/applyMigration.ts
3. Verify with: npx tsx src/scripts/verifyMigration.ts
4. Restart the server