changemaker.lite/mkdocs/docs/v2/user-guides/admin-guide.md

# Administrator Guide

## Overview

The Administrator role is the highest-level role in Changemaker Lite. As an administrator, you have complete control over the platform, including:

- **User management**: Create, edit, suspend, and delete user accounts
- **Campaign oversight**: Manage all advocacy campaigns and moderate responses
- **Location and mapping**: Import locations, create territorial cuts, and organize canvassing efforts
- **Volunteer coordination**: Create shifts, manage signups, and monitor canvassing activity
- **Site configuration**: Configure global settings, themes, email, and feature toggles
- **Content management**: Create landing pages, edit email templates, and manage media library
- **Monitoring**: View queue status, geocoding quality, and system health

This guide will walk you through all administrative functions in Changemaker Lite V2.

---

## Getting Started

### First Login

When you first access Changemaker Lite, you'll log in at the admin portal URL:

```
https://app.cmlite.org
```

Or if running locally:

```
http://localhost:3000
```

**Default credentials** (change immediately after first login):

- **Email**: `admin@example.com`
- **Password**: `Admin123!`

!!! danger "Security Critical"
    The default password is publicly known. Change it immediately after your first login to prevent unauthorized access.

**Screenshot placeholder**: *Login page showing email/password fields and "Remember me" checkbox*

### Dashboard Overview

After logging in, you'll see the Administrator Dashboard, which provides an at-a-glance overview of your platform:

**Key dashboard sections:**

1. **Statistics Cards**
   - Total users (breakdown by role)
   - Active campaigns
   - Total locations
   - Active canvass sessions

2. **Recent Activity Feed**
   - New user registrations
   - Campaign responses
   - Shift signups
   - Canvass visits

3. **Quick Actions**
   - Create new campaign
   - Import locations
   - Create volunteer shift
   - View email queue

4. **System Health**
   - API status
   - Database connectivity
   - Redis cache status
   - Queue worker status

**Screenshot placeholder**: *Dashboard showing statistics cards, activity feed, and quick action buttons*

### Changing Your Password

!!! warning "Required First Step"
    You must change the default password before performing any other administrative tasks.

**To change your password:**

1. Click your email address in the top-right corner
2. Select **"Change Password"** from the dropdown
3. Enter your current password
4. Enter new password (must meet requirements below)
5. Confirm new password
6. Click **"Update Password"**

**Password requirements:**

- Minimum 12 characters
- At least one uppercase letter (A-Z)
- At least one lowercase letter (a-z)
- At least one digit (0-9)
- Cannot reuse recent passwords

**Screenshot placeholder**: *Change password modal showing current/new password fields and requirements checklist*

### Navigating the Admin Interface

The admin interface uses a sidebar navigation with the following sections:

**Main Navigation:**

- **Dashboard** — Overview and quick actions
- **Influence** — Campaigns, responses, representatives, email queue
- **Map** — Locations, cuts, shifts, map settings, data quality
- **Canvass** — Dashboard, sessions, activity reports
- **Content** — Landing pages, email templates, media library
- **Services** — Listmonk, Pangolin, docs, integrations
- **Observability** — Monitoring, metrics, alerts
- **Users** — User management
- **Settings** — Global site settings

**Screenshot placeholder**: *Sidebar navigation showing expanded Influence and Map sections*

---

## User Management

### Creating Users

**To create a new user:**

1. Navigate to **Users** in the sidebar
2. Click **"Create User"** button (top-right)
3. Fill in user details:
   - **Email**: User's email address (must be unique)
   - **Name**: User's full name
   - **Password**: Temporary password (user should change on first login)
   - **Role**: Select from dropdown (see roles below)
   - **Status**: ACTIVE or SUSPENDED
4. Click **"Create"**

The new user will receive a welcome email (if email is configured) with their login credentials.

**Screenshot placeholder**: *Create User modal showing email, name, password, role dropdown, and status toggle*

### Understanding Roles

Changemaker Lite has five user roles with different permission levels:

#### 1. SUPER_ADMIN (You)

- **Access**: Everything
- **Capabilities**: All administrative functions, user management, site configuration
- **Use case**: Primary administrator(s)

#### 2. INFLUENCE_ADMIN

- **Access**: Influence module only
- **Capabilities**:
  - Create and manage campaigns
  - Moderate responses
  - View representative cache
  - Monitor email queue
- **Restrictions**: Cannot manage users, locations, or site settings
- **Use case**: Campaign managers who don't need full admin access

#### 3. MAP_ADMIN

- **Access**: Map module only
- **Capabilities**:
  - Import and manage locations
  - Create cuts
  - Organize shifts
  - Monitor canvassing
- **Restrictions**: Cannot manage users, campaigns, or site settings
- **Use case**: Field organizers, volunteer coordinators

#### 4. USER

- **Access**: Volunteer portal only
- **Capabilities**:
  - View assigned shifts
  - Start canvassing sessions
  - Record door visits
  - View own activity
- **Restrictions**: Cannot access admin areas
- **Use case**: Regular volunteers

#### 5. TEMP

- **Access**: Very limited, volunteer portal only
- **Capabilities**:
  - Sign up for public shifts (creates TEMP account automatically)
  - Cannot start canvassing sessions
- **Restrictions**: Cannot access most features until upgraded to USER
- **Use case**: Anonymous shift signups (converted to USER by admin)

!!! tip "Role Upgrading"
    You can upgrade TEMP users to USER role to give them full volunteer access. This is common after a volunteer attends their first shift.

**Screenshot placeholder**: *User list table showing users with different roles and color-coded role badges*

### Managing Existing Users

The **Users** page shows all user accounts in a searchable, filterable table.

**Table columns:**

- **Name** — User's full name
- **Email** — Login email
- **Role** — Current role (color-coded badge)
- **Status** — ACTIVE (green) or SUSPENDED (red)
- **Last Login** — Most recent login timestamp
- **Created** — Account creation date
- **Actions** — Edit, suspend/activate, delete

**Available filters:**

- **Search**: Search by name or email
- **Role filter**: Show only specific roles
- **Status filter**: Active, suspended, or all
- **Date range**: Filter by creation date

**Screenshot placeholder**: *Users table with search bar, role filter dropdown, and action buttons*

### Editing Users

**To edit a user:**

1. Click the **Edit** icon (pencil) in the Actions column
2. Modify any of:
   - Name
   - Email (must remain unique)
   - Role (change permissions)
   - Status (activate/suspend)
3. Click **"Save"**

!!! warning "Email Changes"
    Changing a user's email will require them to log in with the new email address. Notify them before making this change.

### Suspending Users

**To temporarily disable a user account:**

1. Find the user in the table
2. Click **"Suspend"** in the Actions column
3. Confirm suspension

Suspended users:

- Cannot log in
- Existing sessions are invalidated immediately
- Can be reactivated at any time
- Data and history are preserved

**When to suspend:**

- Volunteer is temporarily unavailable
- Security concerns (investigate before deleting)
- User requests account pause

**Screenshot placeholder**: *Suspend confirmation dialog explaining effects*

### Password Resets

**To reset a user's password:**

1. Edit the user
2. Click **"Reset Password"**
3. Choose one of:
   - **Generate temporary password** (shown on screen, expires in 24 hours)
   - **Send reset email** (user clicks link to set new password)
4. Provide temporary password to user securely (not via email)

!!! tip "Security Best Practice"
    Always use "Send reset email" option when possible. Only generate temporary passwords for in-person support scenarios.

### Deleting Users

!!! danger "Permanent Action"
    Deleting a user is permanent and cannot be undone. All associated data (canvass visits, responses, etc.) will be anonymized.

**To delete a user:**

1. Click the **Delete** icon (trash) in the Actions column
2. Type the user's email to confirm
3. Click **"Delete Permanently"**

**When deletion is appropriate:**

- Duplicate accounts
- Test accounts in production
- User requests account deletion (GDPR compliance)

**Data handling on deletion:**

- User account record is deleted
- Associated content (responses, visits) remains but user reference is nullified
- Email queue jobs remain (email address is preserved for audit)

### Viewing Login Activity

**To see recent login activity:**

1. Navigate to **Users**
2. Check the **"Last Login"** column
3. Click on a user to see detailed login history (if audit logging is enabled)

**Screenshot placeholder**: *User detail view showing login history table with timestamps and IP addresses*

---

## Campaign Management

### Campaign Overview

Campaigns are at the heart of the Influence module. A campaign allows citizens to:

1. Enter their postal code
2. Find their elected representatives
3. Send advocacy emails
4. Share their story on a public response wall

As an administrator, you can create, configure, publish, and monitor campaigns.

### Creating a Campaign

**To create a new campaign:**

1. Navigate to **Influence > Campaigns**
2. Click **"Create Campaign"** (top-right)
3. Fill in the campaign form (see fields below)
4. Click **"Create"**

**Required fields:**

**Basic Information:**

- **Title**: Campaign name (shown to public)
  - Example: "Protect Our Climate"
- **Slug**: URL-friendly identifier (auto-generated from title)
  - Example: `protect-our-climate`
  - Used in public URL: `/campaigns/protect-our-climate`
- **Description**: Campaign overview (supports HTML)
  - Shown on campaign listing page
  - Recommended: 2-3 sentences

**Email Configuration:**

- **Email Subject**: Subject line for advocacy emails
  - Example: "Please support climate action legislation"
  - Variables supported: `{{USER_NAME}}`, `{{REP_NAME}}`
- **Email Body**: The email message citizens send
  - HTML editor available
  - Variables: `{{USER_NAME}}`, `{{USER_EMAIL}}`, `{{REP_NAME}}`, `{{REP_EMAIL}}`, `{{USER_MESSAGE}}`
  - Preview before publishing

**Targeting:**

- **Government Level**: FEDERAL, PROVINCIAL, or MUNICIPAL
  - Determines which representatives are looked up
  - Can select multiple levels

**Screenshot placeholder**: *Create Campaign form showing title, slug, description, email subject, and body editor*

### Understanding Feature Flags

Campaigns have 12 feature flags that control functionality:

#### Core Features

1. **Published**
   - Controls public visibility
   - Unpublished campaigns only visible to admins
   - Toggle to launch/pause campaign

2. **Featured**
   - Featured campaigns appear at top of listing page
   - Use for high-priority campaigns
   - Limit to 2-3 featured campaigns

3. **Has Response Wall**
   - Enables public response wall
   - Citizens can share their story after emailing
   - Responses require admin approval (unless `auto_approve_responses`)

4. **Collect Phone Numbers**
   - Adds optional phone number field
   - Used for call-in campaigns
   - Numbers stored for admin use

5. **Track Calls**
   - Adds "I called my representative" button
   - Tracks call attempts separately from emails
   - Good for blended campaigns

#### Advanced Features

6. **Require Verification**
   - Sends verification email before submitting
   - Prevents spam and bot submissions
   - Recommended for public campaigns

7. **Auto Approve Responses**
   - Response wall submissions appear immediately
   - No admin moderation required
   - Only use for trusted campaigns

8. **Allow Anonymous**
   - Citizens can submit without creating account
   - Reduces friction but limits tracking
   - Good for privacy-sensitive topics

9. **Custom Recipients**
   - Override representative lookup
   - Send to specific email addresses
   - Use for non-government campaigns

10. **Show Progress Bar**
    - Displays email count goal and progress
    - Motivates participation
    - Requires setting `email_goal` field

11. **Disable After Date**
    - Automatically unpublish after specified date
    - Good for time-sensitive campaigns
    - Requires setting `disable_date` field

12. **Enable Comments**
    - Allow comments on response wall entries
    - Creates discussion threads
    - Requires moderation

**Screenshot placeholder**: *Campaign feature flags showing toggles for all 12 flags with descriptive labels*

!!! tip "Recommended Defaults"
    For most campaigns, enable: **Published**, **Has Response Wall**, **Require Verification**. Leave others off unless specifically needed.

### Configuring Email Template

The email template is what citizens send to their representatives. Make it:

**Effective email guidelines:**

- **Personal**: Use variables like `{{USER_NAME}}` to personalize
- **Clear**: State the ask in first paragraph
- **Specific**: Reference specific legislation or issue
- **Respectful**: Professional tone, even if issue is urgent
- **Actionable**: Tell representatives exactly what you want them to do

**Example template:**

```
Subject: Please vote YES on Bill C-123 for climate action

Dear {{REP_NAME}},

My name is {{USER_NAME}}, and I am a constituent in your riding. I'm writing to urge you to vote YES on Bill C-123, the Climate Action Framework.

Climate change is the defining issue of our generation. This bill provides a realistic pathway to reduce emissions while protecting jobs and supporting workers.

I'm specifically asking you to:
1. Vote YES on Bill C-123 when it comes to the floor
2. Speak publicly in support of climate action
3. Oppose any amendments that weaken the bill

Thank you for considering my views. I look forward to your response.

Sincerely,
{{USER_NAME}}
{{USER_EMAIL}}

---
{{USER_MESSAGE}}
```

**Available variables:**

- `{{USER_NAME}}` — Citizen's full name
- `{{USER_EMAIL}}` — Citizen's email address
- `{{USER_PHONE}}` — Citizen's phone (if collected)
- `{{REP_NAME}}` — Representative's name
- `{{REP_EMAIL}}` — Representative's email
- `{{REP_TITLE}}` — Representative's title (MP, MPP, Councillor)
- `{{USER_MESSAGE}}` — Custom message from citizen (optional field)

**Screenshot placeholder**: *Email template editor showing subject and body fields with variable insertion dropdown*

### Publishing a Campaign

Before publishing, verify:

- [ ] Email template is proofread (send test email to yourself)
- [ ] Feature flags are configured correctly
- [ ] Representative lookup is working (test with your postal code)
- [ ] Response wall moderation is ready (if enabled)

**To publish:**

1. Edit the campaign
2. Toggle **"Published"** flag to ON
3. Click **"Save"**

The campaign is now live at `/campaigns/[slug]`.

**Promoting your campaign:**

- Share direct link: `https://yourdomain.org/campaigns/protect-our-climate`
- Embed in email newsletter
- Post on social media
- Add to landing page

**Screenshot placeholder**: *Published campaign card on public campaigns listing page*

### Monitoring Email Sends

**To view email statistics:**

1. Navigate to **Influence > Campaigns**
2. Click **"Emails"** button in the Actions column for your campaign

The **Campaign Emails** drawer shows:

**Statistics:**

- Total emails sent
- Successful deliveries
- Failed deliveries
- Emails waiting in queue

**Email list table:**

- Recipient name and email
- Status (PENDING, SENT, FAILED)
- Sent timestamp
- Representative targeted
- Error message (if failed)

**Actions:**

- **Retry failed**: Re-queue failed emails
- **Export CSV**: Download full email list

**Screenshot placeholder**: *Campaign Emails drawer showing statistics cards and email list table*

### Managing the Email Queue

The email queue processes advocacy emails asynchronously using BullMQ.

**To monitor queue health:**

1. Navigate to **Influence > Email Queue**

**Queue statistics:**

- **Waiting**: Emails queued but not yet processing
- **Active**: Emails currently being sent
- **Completed**: Successfully sent emails (last 24 hours)
- **Failed**: Failed emails requiring retry
- **Delayed**: Scheduled for future sending

**Queue controls:**

- **Pause Queue**: Stop processing new emails (emergencies only)
- **Resume Queue**: Restart after pause
- **Clean Completed**: Remove old completed jobs (frees memory)
- **Retry Failed**: Re-queue all failed emails

!!! warning "Queue Pausing"
    Only pause the queue during system maintenance or if email configuration is broken. Citizens expect immediate sends.

**Screenshot placeholder**: *Email Queue page showing statistics cards, job counts, and control buttons*

### Moderating Responses

If your campaign has **"Has Response Wall"** enabled, citizens can share their stories publicly.

**To moderate responses:**

1. Navigate to **Influence > Responses**
2. Use filters to find pending responses
3. Review each response
4. Approve or reject

**Response filters:**

- **Campaign**: Filter by specific campaign
- **Status**: PENDING, APPROVED, REJECTED
- **Search**: Search response text
- **Date range**: Filter by submission date

**Response table columns:**

- **Name**: Citizen's name
- **Campaign**: Which campaign
- **Status**: Approval status (color-coded)
- **Upvotes**: Number of upvotes received
- **Submitted**: Submission date
- **Actions**: View, approve, reject, delete

**Screenshot placeholder**: *Responses table with filter controls and status badges*

**To review a response:**

1. Click **"View"** in Actions column
2. Read full response text
3. Decide:
   - **Approve**: Make public (appears on response wall)
   - **Reject**: Hide from public (not deleted)
   - **Delete**: Permanently remove

**Moderation guidelines:**

**Approve responses that:**

- Are authentic personal stories
- Relate to the campaign issue
- Use respectful language
- Add value to the public conversation

**Reject responses that:**

- Contain profanity or hate speech
- Are spam or off-topic
- Violate privacy (include private information about others)
- Are duplicate submissions

**Screenshot placeholder**: *Response detail modal showing full text, citizen info, and approve/reject buttons*

---

## Location Management

### Location Data Overview

Locations represent physical addresses where canvassing occurs. Each location has:

- **Address**: Street address, city, province, postal code
- **Coordinates**: Latitude/longitude (from geocoding)
- **Metadata**: Building type, federal district, unit count
- **Cut assignment**: Which territorial cut it belongs to
- **Canvass history**: Visits, outcomes, support levels

### Importing Locations from CSV

**To import locations:**

1. Navigate to **Map > Locations**
2. Click **"Import CSV"** button
3. Upload CSV file
4. Map CSV columns to location fields
5. Click **"Import"**

**Required CSV columns:**

- **address** — Full street address
- **city** — City name
- **province** — Province/state code (e.g., "ON", "BC")
- **postalCode** — Postal code (e.g., "K1A 0B1")

**Optional columns:**

- **latitude** — Pre-geocoded latitude
- **longitude** — Pre-geocoded longitude
- **buildingType** — RESIDENTIAL, APARTMENT, BUSINESS
- **unitCount** — Number of units in building
- **federalDistrict** — Electoral district
- **notes** — Internal notes

**CSV example:**

```csv
address,city,province,postalCode,buildingType
"123 Main St","Ottawa","ON","K1A 0B1","RESIDENTIAL"
"456 Queen St E","Toronto","ON","M5A 1T1","APARTMENT"
"789 Granville St","Vancouver","BC","V6Z 1K3","BUSINESS"
```

!!! tip "Excel to CSV"
    If your data is in Excel, use "Save As" > "CSV (Comma delimited)" to export.

**Screenshot placeholder**: *CSV import dialog showing file upload, column mapping interface, and preview table*

### NAR Import (Canadian Electoral Data)

For Canadian campaigns, you can import official electoral data from Elections Canada NAR (National Address Register) files.

**To import NAR data:**

1. Navigate to **Map > Locations**
2. Click **"NAR Import"** button
3. Select province
4. Choose NAR dataset (year)
5. Apply filters:
   - City filter (optional)
   - Postal code filter (optional)
   - Cut filter (assign to specific cut)
   - Residential only (exclude commercial)
6. Click **"Start Import"**

The import runs server-side and can take several minutes for large provinces.

**NAR data includes:**

- Precise civic addresses (from Address files)
- Geocoded coordinates (from Location files)
- Federal electoral districts
- Building use (residential, commercial, institutional)

**Screenshot placeholder**: *NAR Import modal showing province selector, dataset picker, and filter options*

!!! note "NAR Data Source"
    NAR data must be obtained from Elections Canada and placed in the `/data` directory on the server. Contact your system administrator.

### Geocoding Addresses

Geocoding converts addresses to latitude/longitude coordinates for map display.

**Automatic geocoding:**

- CSV imports without lat/lng are automatically geocoded
- NAR imports include pre-geocoded coordinates
- Manual location creation triggers geocoding

**Manual geocoding:**

1. Navigate to **Map > Locations**
2. Filter for **"Ungeocoded"** locations
3. Select locations to geocode
4. Click **"Geocode Selected"** (bulk action)

**Geocoding providers** (tried in order):

1. **Nominatim** (OpenStreetMap) — Free, no API key required
2. **ArcGIS** — Free tier, accurate for North America
3. **Photon** — Free, Europe-focused
4. **Mapbox** — Requires API key, very accurate
5. **Google** — Requires API key, most accurate
6. **LocationIQ** — Requires API key, Nominatim-based

!!! tip "Geocoding Quality"
    Check **Map > Data Quality** to review geocoding confidence levels. Re-geocode low-confidence addresses.

**Screenshot placeholder**: *Locations table with "Geocode Selected" button and geocoding status column*

### Creating Cuts

Cuts are geographic areas (wards, neighborhoods, districts) used to organize canvassing.

**To create a cut:**

1. Navigate to **Map > Cuts**
2. Click the **"Map Drawing"** tab
3. Click **"Start Drawing"**
4. Click on the map to add polygon vertices
5. Close the polygon (click near first point)
6. Fill in cut details:
   - **Name**: Cut identifier (e.g., "Ward 5", "Downtown")
   - **Category**: WARD, NEIGHBORHOOD, DISTRICT, or CUSTOM
   - **Color**: Display color on map
   - **Description**: Internal notes
7. Click **"Save Cut"**

**Cut best practices:**

- **Size**: 200-500 locations per cut (manageable for canvassing)
- **Boundaries**: Use natural boundaries (roads, rivers, parks)
- **Naming**: Use official ward/district names when available
- **Colors**: Use distinct colors for adjacent cuts

**Screenshot placeholder**: *Cut drawing map interface showing polygon being drawn with vertex markers*

### Assigning Locations to Cuts

**Automatic assignment** (during cut creation):

- Locations inside polygon are automatically assigned
- Uses point-in-polygon algorithm

**Manual assignment:**

1. Navigate to **Map > Locations**
2. Select locations to assign
3. Choose **"Assign to Cut"** from bulk actions
4. Select target cut
5. Click **"Assign"**

**Viewing cut assignments:**

- Location table has **"Cut"** column
- Filter locations by cut using dropdown

**Screenshot placeholder**: *Bulk action modal showing "Assign to Cut" with cut selector dropdown*

### Managing Locations

**To edit a location:**

1. Navigate to **Map > Locations**
2. Click **"Edit"** in Actions column
3. Modify fields:
   - Address details
   - Coordinates (manually adjust map pin)
   - Building type
   - Unit count
   - Notes
   - Cut assignment
4. Click **"Save"**

**To delete locations:**

1. Select locations in table
2. Choose **"Delete"** from bulk actions
3. Confirm deletion

!!! warning "Canvass History"
    Deleting a location preserves associated canvass visits (visits are linked to coordinates, not location records).

**Screenshot placeholder**: *Edit Location modal showing address fields, map with draggable pin, and metadata fields*

### Exporting Walk Sheets

Walk sheets are printable lists of addresses for door-to-door canvassing.

**To generate a walk sheet:**

1. Navigate to **Map > Locations**
2. Filter to specific cut
3. Click **"Walk Sheet"** in the cut's action menu

OR:

1. Navigate to **Canvass > Walk Sheet**
2. Select cut from dropdown
3. Configure settings (see below)
4. Click **"Print"**

**Walk sheet settings** (from Map > Map Settings):

- **Header text**: Organization name, campaign info
- **Instructions**: How to use the walk sheet
- **QR code**: Include QR code linking to volunteer canvass map
- **Sorting**: Sort by street name or walking route
- **Include map**: Embed cut map on first page

**Walk sheet contents:**

- Cut name and statistics
- QR code (volunteers scan to start canvass session)
- Location table:
  - Address
  - Unit count
  - Last visit date
  - Last outcome
  - Notes field (blank for volunteers to fill)

**Screenshot placeholder**: *Walk sheet PDF preview showing header, QR code, and address table*

---

## Volunteer Management

### Creating Shifts

Shifts are scheduled volunteer canvassing sessions assigned to specific cuts.

**To create a shift:**

1. Navigate to **Map > Shifts**
2. Click **"Create Shift"**
3. Fill in shift details:
   - **Title**: Shift name (e.g., "Saturday Morning Canvass - Ward 5")
   - **Description**: Additional details for volunteers
   - **Start Time**: Shift start date and time
   - **End Time**: Shift end date and time
   - **Cut**: Which cut to canvass (optional, but recommended)
   - **Max Signups**: Capacity limit (0 = unlimited)
   - **Meeting Location**: Where volunteers should meet
4. Click **"Create"**

**Screenshot placeholder**: *Create Shift modal showing date/time picker, cut selector, and capacity field*

!!! tip "Cut Assignment"
    Shifts assigned to a cut appear in the volunteer portal under "My Assignments" for volunteers who signed up. Volunteers can start canvassing directly from their dashboard.

### Managing Shift Signups

**To view shift signups:**

1. Navigate to **Map > Shifts**
2. Click **"Signups"** in Actions column

The signups drawer shows:

- **Total signups** vs capacity
- **Signup list**: Name, email, role, signup date
- **Actions**: Remove signup, upgrade TEMP users to USER

**Signup sources:**

- **Public signup form**: `/shifts` page (creates TEMP users)
- **Admin-created**: You manually add volunteers
- **Volunteer portal**: USER-role volunteers sign up themselves

**Screenshot placeholder**: *Shift Signups drawer showing capacity gauge and signup list table*

### Emailing Shift Volunteers

**To email all volunteers in a shift:**

1. Navigate to **Map > Shifts**
2. Click **"Signups"** for the shift
3. Click **"Email All"** button
4. Compose email:
   - **Subject**: Email subject line
   - **Body**: Message (supports HTML)
   - **Variables**: Use `{{NAME}}`, `{{SHIFT_TITLE}}`, `{{SHIFT_START}}`
5. Click **"Send"**

**Common email scenarios:**

- **Reminder**: Day before shift
- **Cancellation**: Weather or other issues
- **Location change**: Meeting point updated
- **Follow-up**: Thank you after shift

**Screenshot placeholder**: *Email Volunteers modal showing subject, body editor, and variable insertion buttons*

### Monitoring Canvass Sessions

**To view active canvass sessions:**

1. Navigate to **Canvass > Dashboard**

The dashboard shows:

**Statistics cards:**

- **Active sessions**: Currently in progress
- **Total visits today**: Doors knocked
- **Completed sessions**: Finished today
- **Average session duration**

**Activity feed:**

- Real-time visit stream
- Shows: Volunteer name, address, outcome, timestamp
- Updates every 30 seconds

**Cut progress table:**

- Progress by cut (% of locations visited)
- Session count per cut
- Visit count per cut

**Leaderboard:**

- Top volunteers by visit count
- Session count
- Success rate (SPOKE_WITH outcomes)

**Screenshot placeholder**: *Canvass Dashboard showing stats cards, activity feed, and leaderboard*

### Viewing Canvass Activity Reports

**To see detailed canvassing data:**

1. Navigate to **Canvass > Dashboard**
2. Use filters:
   - **Date range**: Last 7 days, last 30 days, custom
   - **Cut**: Specific cut or all
   - **Volunteer**: Specific volunteer or all
   - **Outcome**: Filter by visit outcome

**Exportable reports:**

- **Visit history CSV**: All visits with outcomes, notes, timestamps
- **Support levels CSV**: LEVEL_1 through LEVEL_4 breakdown
- **Session summary CSV**: Session duration, visit count, volunteer info

**Screenshot placeholder**: *Activity report filters and export buttons*

---

## Site Configuration

### Site Settings

**To configure global site settings:**

1. Navigate to **Settings** (gear icon in sidebar)

**Available settings:**

**Branding:**

- **Site Name**: Your organization name
- **Site URL**: Public website URL
- **Logo URL**: URL to your logo image
- **Primary Color**: Brand color (hex code)
- **Secondary Color**: Accent color

**Email Configuration:**

- **From Name**: Sender name for system emails
- **From Email**: Sender email address
- **SMTP Host**: Email server hostname
- **SMTP Port**: Usually 587 (TLS) or 465 (SSL)
- **SMTP Username**: SMTP authentication username
- **SMTP Password**: SMTP authentication password
- **Test Mode**: Send to MailHog instead of real SMTP (dev only)

**Representative API:**

- **Represent API Base URL**: Usually `https://represent.opennorth.ca`
- **API Key**: If required by provider
- **Cache TTL**: How long to cache representative data (hours)

**Feature Toggles:**

- **Enable Media Features**: Enable video library and media management
- **Enable Listmonk Sync**: Sync contacts to Listmonk newsletter platform
- **Allow Public Shift Signup**: Anyone can sign up for shifts (creates TEMP users)
- **Require Email Verification**: Campaign responses require email confirmation

**Screenshot placeholder**: *Settings page showing branding, email, and feature toggle sections*

!!! tip "Test Email Configuration"
    After changing SMTP settings, click "Send Test Email" to verify configuration before publishing campaigns.

### Map Settings

**To configure map defaults:**

1. Navigate to **Map > Map Settings**

**Map Configuration:**

- **Default Center**: Latitude/longitude for map center
  - Used on public map and admin map
  - Usually your city center
- **Default Zoom**: Zoom level (1-18)
  - 12 = city-wide view
  - 15 = neighborhood view
- **Enable Fullscreen**: Allow fullscreen button on public map
- **Enable Geolocation**: Allow "Find My Location" button

**Walk Sheet Configuration:**

- **Header Text**: Appears at top of walk sheets
- **Footer Text**: Appears at bottom
- **Include QR Code**: Add QR code linking to volunteer map
- **QR Code Size**: Small, medium, or large
- **Instructions**: Text explaining how to use walk sheet

**Screenshot placeholder**: *Map Settings page showing map center picker and walk sheet config*

### Feature Toggles

Feature toggles allow you to enable/disable major platform features without code changes.

**To manage feature toggles:**

1. Navigate to **Settings**
2. Scroll to **Feature Toggles** section
3. Toggle features on/off
4. Click **"Save"**

**Available toggles:**

**ENABLE_MEDIA_FEATURES**

- Enables Media Library and video management
- Shows Media menu in sidebar
- Allows video uploads and public media gallery
- Requires media-api service running

**ENABLE_LISTMONK_SYNC**

- Enables newsletter integration
- Syncs campaign participants to Listmonk lists
- Shows Listmonk menu in sidebar
- Requires Listmonk service configured

**ALLOW_PUBLIC_SHIFT_SIGNUP**

- Public can sign up for shifts at `/shifts`
- Creates TEMP user accounts automatically
- Shows shifts on public pages
- Disable for invitation-only volunteering

**REQUIRE_EMAIL_VERIFICATION**

- Campaign responses require email verification
- Prevents spam and fake submissions
- Sends verification link before recording response
- Recommended for public campaigns

**Screenshot placeholder**: *Feature Toggles section showing four toggles with descriptions*

!!! warning "Media Features"
    Enabling media features requires the `media-api` Docker container to be running. Check with your system administrator.

---

## Email Templates

### Understanding Email Templates

Changemaker Lite uses email templates for system-generated emails:

**System templates:**

- **Welcome Email**: Sent to new users
- **Password Reset**: Sent when user requests password reset
- **Shift Confirmation**: Sent when volunteer signs up for shift
- **Shift Reminder**: Sent day before shift
- **Response Verification**: Sent to verify campaign response

**Custom templates:**

- You can create custom templates for specific needs
- Use in shift emails, campaign follow-ups, etc.

### Editing Templates

**To edit an email template:**

1. Navigate to **Content > Email Templates**
2. Click **"Edit"** for the template
3. Modify:
   - **Subject**: Email subject line
   - **HTML Body**: Rich email content
   - **Plain Text Body**: Fallback for text-only clients
4. Use variables (e.g., `{{USER_NAME}}`, `{{SHIFT_TITLE}}`)
5. Click **"Preview"** to see rendered email
6. Click **"Save"**

**Screenshot placeholder**: *Email Template Editor showing subject field, HTML editor, and variable buttons*

### Available Variables

Templates support variable interpolation:

**User variables:**

- `{{USER_NAME}}` — User's full name
- `{{USER_EMAIL}}` — User's email address

**Shift variables:**

- `{{SHIFT_TITLE}}` — Shift name
- `{{SHIFT_START}}` — Start date/time
- `{{SHIFT_END}}` — End date/time
- `{{SHIFT_LOCATION}}` — Meeting location
- `{{SHIFT_CUT}}` — Cut name

**Campaign variables:**

- `{{CAMPAIGN_TITLE}}` — Campaign name
- `{{CAMPAIGN_URL}}` — Link to campaign page

**System variables:**

- `{{SITE_NAME}}` — Your organization name
- `{{SITE_URL}}` — Website URL

**Screenshot placeholder**: *Variable reference table in template editor sidebar*

### Testing Templates

**To test an email template:**

1. Edit the template
2. Click **"Send Test Email"**
3. Enter your email address
4. Click **"Send"**

You'll receive the email with sample data filled in for variables.

!!! tip "Always Test"
    Test templates before using them in production. Check both HTML and plain text versions.

---

## Media Library

!!! note "Optional Feature"
    Media features must be enabled via **Settings > Feature Toggles > ENABLE_MEDIA_FEATURES**. Requires media-api service.

### Uploading Videos

**To upload a video:**

1. Navigate to **Content > Media > Library**
2. Click **"Upload Video"**
3. Either:
   - Drag and drop video file
   - Click to browse and select file
4. Fill in metadata:
   - **Title**: Video title
   - **Description**: Video description
   - **Producer**: Organization or creator
   - **Creator**: Individual creator/director
   - **Tags**: Comma-separated tags
   - **Directory**: Organize into folders
5. Click **"Upload"**

**Supported formats:**

- MP4 (recommended)
- MOV
- AVI
- MKV
- WebM
- M4V
- FLV

**File size limit:** 10 GB per file

**Screenshot placeholder**: *Upload Video modal showing drag-drop area, metadata form, and progress bar*

### Automatic Metadata Extraction

When you upload a video, the system automatically extracts:

- **Duration**: Length in seconds
- **Dimensions**: Width x height in pixels
- **Orientation**: PORTRAIT, LANDSCAPE, or SQUARE
- **Quality**: SD, HD, FULL_HD, or 4K
- **Has Audio**: Boolean
- **File Size**: Bytes

This metadata is used for filtering and organizing videos.

### Organizing the Library

**Directory structure:**

- Create directories to organize videos
- Directories are simple text paths (e.g., "events/2024", "testimonials")
- Set directory when uploading or editing

**Filtering videos:**

- **Search**: Search title, description, tags
- **Directory**: Filter by directory
- **Quality**: Filter by SD, HD, etc.
- **Orientation**: Portrait, landscape, square
- **Locked**: Show only locked or unlocked

**Sorting:**

- Upload date (newest first)
- Title (A-Z)
- Duration (shortest first)

**Screenshot placeholder**: *Media Library showing directory tree, filters, and video grid*

### Sharing Videos Publicly

**To make videos public:**

1. Navigate to **Content > Media > Shared Media**
2. Select videos from library
3. Choose category:
   - **TESTIMONIAL**
   - **EVENT**
   - **EDUCATIONAL**
   - **PROMOTIONAL**
4. Click **"Share"**

Shared videos appear on the public media gallery at `/media`.

**To unshare videos:**

1. Go to **Shared Media**
2. Select videos
3. Click **"Unshare"**

**Screenshot placeholder**: *Shared Media page showing category filter and share/unshare buttons*

### Locking Videos

**Locked videos** cannot be deleted or moved. Use locks to protect important content.

**To lock a video:**

1. Select video in library
2. Click **"Lock"** (padlock icon)

**To unlock:**

1. Select locked video
2. Click **"Unlock"**

!!! warning "Lock Before Sharing"
    Lock videos before sharing publicly to prevent accidental deletion.

---

## Monitoring & Reports

### Viewing Queue Status

**To monitor the email queue:**

1. Navigate to **Influence > Email Queue**

**Key metrics:**

- **Waiting**: Emails queued for sending
  - High number = slow processing (check SMTP)
- **Active**: Currently processing
  - Should be 1-5 (concurrent workers)
- **Completed**: Sent in last 24 hours
- **Failed**: Delivery failures
  - Click "View Failed" to see error messages

**Queue health indicators:**

- **Green**: < 50 waiting, < 5 failed
- **Yellow**: 50-200 waiting, 5-20 failed
- **Red**: > 200 waiting, > 20 failed

**Screenshot placeholder**: *Email Queue dashboard showing job counts with color-coded health indicators*

### Geocoding Quality Dashboard

**To review geocoding quality:**

1. Navigate to **Map > Data Quality**

**Quality metrics:**

- **Total locations**: All location records
- **Geocoded**: Have lat/lng coordinates
- **Ungeocoded**: Missing coordinates
- **Low confidence**: Confidence < 0.5
- **Medium confidence**: 0.5-0.8
- **High confidence**: > 0.8

**Quality breakdown:**

- **Provider distribution**: Which geocoding service was used
- **Confidence histogram**: Distribution of confidence scores
- **Error analysis**: Common geocoding failures

**Actions:**

- **Re-geocode low confidence**: Retry with different provider
- **Export ungeocoded**: CSV of failed addresses
- **Manual review**: Edit addresses and re-geocode

**Screenshot placeholder**: *Data Quality Dashboard showing geocoding statistics and confidence distribution chart*

### Canvass Completion Statistics

**To view canvass progress:**

1. Navigate to **Canvass > Dashboard**

**Completion metrics:**

- **Locations visited**: Total unique addresses visited
- **Visit rate**: Visits per day/week
- **Completion by cut**: % of each cut visited
- **Outcome breakdown**: % NOT_HOME, REFUSED, SPOKE_WITH, etc.

**Support level analysis:**

- **LEVEL_1** (Strong support): Count and percentage
- **LEVEL_2** (Leaning support): Count and percentage
- **LEVEL_3** (Undecided): Count and percentage
- **LEVEL_4** (Opposition): Count and percentage

**Volunteer performance:**

- **Sessions per volunteer**: Distribution histogram
- **Visits per volunteer**: Leaderboard
- **Average session duration**: Time spent canvassing

**Screenshot placeholder**: *Canvass statistics showing completion gauges, outcome pie chart, and support level breakdown*

### Observability Dashboard

**To monitor system health:**

1. Navigate to **Observability**

The observability dashboard has three tabs:

#### Metrics Tab

- **Custom metrics**: 12 `cm_*` Prometheus metrics
  - API uptime
  - Request counts
  - Email queue size
  - Active sessions
  - Geocoding success rate
- **HTTP metrics**: Request duration, status codes
- **System metrics**: CPU, memory, disk

**Screenshot placeholder**: *Metrics tab showing API uptime gauge and request count graph*

#### Dashboards Tab

- **Links to Grafana dashboards**:
  - API Health (uptime, response times, error rates)
  - Queue Monitoring (email queue, geocoding queue)
  - Canvassing Activity (sessions, visits, outcomes)
- Click dashboard name to open in Grafana

**Screenshot placeholder**: *Dashboards tab showing three dashboard cards with "Open" buttons*

#### Alerts Tab

- **Active alerts**: Currently firing alerts
- **Alert history**: Recent resolved alerts
- **Alert rules**: Configured thresholds
- **Silence alerts**: Temporarily mute alerts

**Common alerts:**

- **API Down**: API not responding
- **High Error Rate**: > 5% requests failing
- **Queue Backed Up**: > 1000 emails waiting
- **Disk Space Low**: < 10% free space

**Screenshot placeholder**: *Alerts tab showing active alert for "Queue Backed Up" with severity and details*

---

## Troubleshooting

### Common Admin Issues

#### Issue: Cannot Log In

**Symptoms:** "Invalid credentials" error

**Solutions:**

1. **Verify email address**: Check for typos, spaces
2. **Try password reset**: Use "Forgot Password" link
3. **Check account status**: Ask another admin if account is suspended
4. **Check browser console**: Look for API errors

#### Issue: Emails Not Sending

**Symptoms:** Emails stuck in "Waiting" status

**Solutions:**

1. **Check SMTP configuration**:
   - Navigate to **Settings**
   - Verify SMTP host, port, username, password
   - Click "Send Test Email"
2. **Check email queue**:
   - Navigate to **Influence > Email Queue**
   - Look for error messages in failed jobs
3. **Check email test mode**:
   - If `EMAIL_TEST_MODE=true`, emails go to MailHog (not real recipients)
   - Change in environment settings
4. **Restart queue worker**:
   - Ask system administrator to restart api service

#### Issue: CSV Import Fails

**Symptoms:** Error during CSV upload

**Solutions:**

1. **Check CSV format**:
   - Must be valid CSV (comma-separated)
   - First row must be headers
   - Required columns: address, city, province, postalCode
2. **Check file encoding**:
   - Use UTF-8 encoding
   - Excel users: "Save As" > "CSV UTF-8"
3. **Check file size**:
   - Maximum 10,000 rows per import
   - Split large files
4. **Check for special characters**:
   - Remove emoji, unusual symbols
   - Use standard quotes ("not "" or '')

#### Issue: Geocoding Fails

**Symptoms:** Addresses remain ungeocoded after import

**Solutions:**

1. **Check address format**:
   - Include full civic address
   - Include city and postal code
   - Use standard abbreviations (St, Ave, Rd)
2. **Check geocoding providers**:
   - Navigate to **Map > Data Quality**
   - See which providers are responding
3. **Try manual geocoding**:
   - Edit location
   - Click and drag map pin to correct position
   - Save
4. **Use NAR data** (Canada only):
   - NAR import includes pre-geocoded coordinates
   - More reliable than automatic geocoding

#### Issue: Map Not Loading

**Symptoms:** Blank map or loading spinner

**Solutions:**

1. **Check browser console**: Look for JavaScript errors
2. **Check internet connection**: Map tiles require network
3. **Try different browser**: Test in Chrome, Firefox
4. **Clear browser cache**: Hard refresh (Ctrl+Shift+R)
5. **Check locations**:
   - Navigate to **Map > Locations**
   - Verify locations have coordinates
   - At least one location needed to display map

#### Issue: Campaign Not Appearing Publicly

**Symptoms:** Campaign visible in admin but not on `/campaigns`

**Solutions:**

1. **Check "Published" flag**:
   - Edit campaign
   - Ensure "Published" toggle is ON
   - Save
2. **Check URL**:
   - Campaign URL is `/campaigns/[slug]`
   - Slug is auto-generated from title
   - Must be unique
3. **Clear browser cache**: Public pages may be cached
4. **Check representative lookup**:
   - Test with your postal code
   - If lookup fails, campaign won't display form

#### Issue: Volunteer Cannot Start Canvass Session

**Symptoms:** Error when volunteer clicks "Start Canvassing"

**Solutions:**

1. **Check shift assignment**:
   - Navigate to **Map > Shifts**
   - Verify shift has a cut assigned
   - Shifts without cuts cannot be canvassed
2. **Check volunteer role**:
   - Navigate to **Users**
   - Verify volunteer is USER role (not TEMP)
   - Upgrade TEMP users to USER
3. **Check cut locations**:
   - Navigate to **Map > Cuts**
   - Verify cut has locations assigned
   - Empty cuts cannot be canvassed
4. **Check for existing session**:
   - Volunteer may have abandoned session
   - Ask admin to close abandoned session

### Getting Help

**Documentation:**

- **Feature docs**: `/docs/v2/features/` (detailed feature guides)
- **API reference**: `/docs/v2/api/` (API endpoint documentation)
- **User guides**: `/docs/v2/user-guides/` (this guide and others)
- **Deployment**: `/docs/v2/deployment/` (server setup, Docker, backups)

**Support channels:**

- **GitHub Issues**: Report bugs, request features
- **Community Forum**: Ask questions, share tips
- **Email Support**: Contact your system administrator

**Before asking for help:**

1. Check browser console for errors (F12)
2. Try in different browser
3. Check server logs (if you have access)
4. Document steps to reproduce issue

---

## Related Documentation

- **[Volunteer Guide](volunteer-guide.md)**: Guide for volunteers using the canvassing portal
- **[Campaign Manager Guide](campaign-manager-guide.md)**: Deep dive on campaign strategy and management
- **[Map Organizer Guide](map-organizer-guide.md)**: Advanced location and territory management
- **[Content Editor Guide](content-editor-guide.md)**: Landing pages and media library
- **[Influence Module](../features/influence.md)**: Technical details on campaigns and email sending
- **[Map Module](../features/map.md)**: Technical details on geocoding and canvassing
- **[API Reference](../api/overview.md)**: REST API documentation for integrations

---

**Last updated**: February 2026 (V2 complete)