# 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](../../layouts/index.md) (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](volunteer-shifts-page.md)

**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](volunteer-map-page.md)

**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](my-activity-page.md)

**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](my-routes-page.md)

**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:

```typescript
// 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:

```typescript
// 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:

```typescript
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:
   - Find nearest unvisited location
   - Add to route
3. 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)

## Related Documentation

- [Frontend Pages Overview](../index.md)
- [Admin Pages](../admin/index.md)
- [Public Pages](../public/index.md)
- [Volunteer Layout](../../layouts/index.md)
- [Canvass Components](../../components/index.md)
- [Canvassing Feature](../../../features/map/canvassing.md)
- [Backend Canvass Module](../../../backend/modules/canvass.md)
- [Volunteer User Guide](../../../user-guides/volunteer-guide.md)