Skip to content

Volunteer Pages

Volunteer pages provide the volunteer portal interface for canvassing activities. These pages require authentication and are optimized for field use with GPS tracking and mobile responsiveness.

Route Context

  • Prefix: /volunteer/*
  • Layout: VolunteerLayout (top navigation)
  • Auth Required: Yes (any role)
  • Theme: Dark theme (consistent with public pages)
  • Mobile: Optimized for mobile/tablet use

Dashboard

Volunteer Dashboard

Route: /volunteer/dashboard

Volunteer overview with:

  • Personal statistics
  • Upcoming assignments
  • Recent activity
  • Quick actions

Features: - Visit count and outcomes - Next shift information - Activity summary - Mobile responsive

Shift Management

Volunteer Shifts Page

Route: /volunteer/assignments

Assigned shifts for logged-in volunteer:

  • Upcoming shifts list
  • Cut information
  • Start canvass button
  • Shift details

Features: - Filter by date - Cut assignment display - Quick start canvassing - Email notifications - Mobile responsive

Note: Only shows shifts with cutId assigned (required for canvassing).

Canvassing

Volunteer Map Page

Route: /volunteer/canvass/:cutId

Full-screen GPS canvass map:

  • Leaflet map with GPS tracking
  • Location markers by status
  • Walking route polyline
  • Bottom sheet toolbar
  • Visit recording form
  • Session timer

Features: - GPS position tracking - Auto-center on position - Color-coded markers: - Red - Not visited - Blue - Next in route - Green - Visited (success outcomes) - Orange - Visited (neutral outcomes) - Red - Visited (negative outcomes) - Click marker to record visit - Walking route algorithm - Session management - Mobile optimized

Full-Screen: - No layout wrapper - Custom header with timer - Bottom sheet controls - Optimized for field use

GPS Tracking: - Watch position API - Blue GPS marker - Accuracy circle - Auto-update every 5 seconds

Visit Recording: - Outcome selection (NOT_HOME, MOVED, REFUSED, etc.) - Notes field - GPS coordinates captured - Rate limited (30/min)

Session Management: - Start/end session - Elapsed timer - Abandoned session cleanup (12h) - Progress tracking

Activity Tracking

My Activity Page

Route: /volunteer/activity

Visit history and statistics:

  • Visit list by date
  • Outcome breakdown
  • Session summary
  • Export options

Features: - Filter by date range - Group by session - Outcome pie chart - Total visit count - Mobile responsive

My Routes Page

Route: /volunteer/routes

Walking route history:

  • Route list by session
  • Distance traveled
  • Time elapsed
  • Location count

Features: - Route visualization - Session details - Statistics summary - Mobile responsive

Volunteer Page Count

Total: 4 volunteer pages

Common Features

Volunteer pages share:

  • Mobile First - Touch-friendly controls
  • GPS Integration - Location tracking
  • Dark Theme - Low-light visibility
  • Session State - Zustand canvass store
  • Real-time Updates - Auto-refresh data
  • Offline Support (future) - Service worker caching

Authentication

All volunteer pages require authentication:

// Volunteer routes use authenticate middleware
router.get('/api/canvass/session', authenticate, ...)

Role-based redirect after login: - ADMIN roles → /app/dashboard - USER/TEMP roles → /volunteer/dashboard

State Management

Volunteer pages use Zustand canvass store:

// stores/canvass.store.ts
interface CanvassStore {
  session: CanvassSession | null;
  locations: CanvassLocation[];
  route: WalkingRoute | null;
  gpsPosition: { lat: number; lng: number } | null;
  currentLocationIndex: number;
  // ... actions
}

GPS Tracking

GPS tracking uses browser Geolocation API:

navigator.geolocation.watchPosition(
  (position) => {
    setGpsPosition({
      lat: position.coords.latitude,
      lng: position.coords.longitude,
    });
  },
  (error) => console.error('GPS error:', error),
  {
    enableHighAccuracy: true,
    timeout: 5000,
    maximumAge: 0,
  }
);

Walking Route Algorithm

Routes are calculated server-side using nearest-neighbor algorithm:

  1. Start at closest location to shift start
  2. For each subsequent location:
  3. Find nearest unvisited location
  4. Add to route
  5. Return ordered location list

Frontend displays route as blue polyline connecting locations.

Visit Outcomes

Available outcomes in recording form:

  • SUCCESS - Successful contact
  • NOT_HOME - No one home
  • MOVED - Resident moved
  • REFUSED - Contact refused
  • WRONG_ADDRESS - Address error
  • INACCESSIBLE - Cannot access
  • OTHER - Other outcome

Session Lifecycle

  1. Start Session - Create session record, generate route
  2. GPS Tracking - Track position, update markers
  3. Visit Locations - Record outcomes, update route
  4. End Session - Close session, save statistics
  5. Abandoned Cleanup - Auto-close after 12 hours

Mobile Optimization

Volunteer pages are optimized for mobile:

  • Touch Targets - Minimum 44px touch areas
  • GPS Integration - Native geolocation
  • Offline Maps (future) - Cached tiles
  • Battery Optimization - Efficient GPS polling
  • Low-Light Mode - Dark theme
  • Network Resilience - Queue failed requests

Performance

GPS canvass map optimizations:

  • Marker clustering for large datasets
  • Route simplification
  • Debounced position updates
  • Lazy loading location details
  • Service worker caching (future)