# User Guides

This section provides step-by-step guides for different user roles and common tasks. Each guide is tailored to specific workflows and responsibilities.

## Role-Based Guides

### [Admin Guide](admin-guide.md)

For system administrators and site managers:

- Initial setup and configuration
- User management
- Site settings
- Service integration
- Monitoring and maintenance
- Security best practices

**Target Audience:** SUPER_ADMIN role

### [Campaign Manager Guide](campaign-manager-guide.md)

For advocacy campaign coordinators:

- Creating campaigns
- Managing representatives
- Email template design
- Response moderation
- Campaign analytics
- Email queue monitoring

**Target Audience:** INFLUENCE_ADMIN role

### [Map Organizer Guide](map-organizer-guide.md)

For field organizing coordinators:

- Location management
- Importing data (CSV, NAR)
- Creating geographic cuts
- Scheduling volunteer shifts
- Monitoring canvassing progress
- Printing walk sheets

**Target Audience:** MAP_ADMIN role

### [Volunteer Guide](volunteer-guide.md)

For field canvassers:

- Viewing shift assignments
- Starting canvass session
- Using GPS map
- Recording visit outcomes
- Tracking personal activity
- Best practices for canvassing

**Target Audience:** USER role

### [Content Editor Guide](content-editor-guide.md)

For content creators:

- Creating landing pages
- Using GrapesJS editor
- Email template creation
- Managing media library
- Publishing content
- SEO best practices

**Target Audience:** SUPER_ADMIN role

## Common Tasks

### Getting Started

1. **First Login**
   - Navigate to http://your-domain.com or http://localhost:3000
   - Login with credentials
   - Change default password
   - Explore dashboard

2. **User Role Redirection**
   - **Admin roles** → `/app/dashboard`
   - **User/volunteer roles** → `/volunteer/dashboard`

### Campaign Workflow

1. **Create Campaign**
   - Navigate to `/app/influence/campaigns`
   - Click "New Campaign"
   - Fill in details
   - Save campaign

2. **Design Email Template**
   - Set email subject
   - Write email body
   - Use variable placeholders
   - Preview template

3. **Launch Campaign**
   - Set to published
   - Share public URL
   - Monitor responses

### Location Workflow

1. **Import Locations**
   - Prepare CSV file
   - Navigate to `/app/map/locations`
   - Click "Import CSV"
   - Map columns
   - Import data

2. **Geocode Addresses**
   - Select ungeocode locations
   - Click "Geocode Selected"
   - Monitor progress
   - Review quality metrics

3. **Create Geographic Cuts**
   - Navigate to `/app/map/cuts`
   - Click "Draw on Map"
   - Draw polygon
   - Save cut
   - Assign locations

### Volunteer Canvassing Workflow

1. **View Assignments**
   - Login as volunteer
   - Navigate to `/volunteer/assignments`
   - View upcoming shifts

2. **Start Canvassing**
   - Click "Start Canvass"
   - Grant GPS permissions
   - Follow walking route
   - Visit locations

3. **Record Visits**
   - Click location marker
   - Select outcome
   - Add notes
   - Submit

4. **End Session**
   - Click "End Session"
   - Review statistics
   - View in activity history

## Task Guides

### Import Canadian Electoral Data (NAR)

1. **Prepare Data**
   - Download NAR 2025 data
   - Place in `/data` directory
   - Ensure Address + Location files present

2. **Import via Admin**
   - Navigate to `/app/map/locations`
   - Click "Import NAR"
   - Select province
   - Apply filters
   - Start import

3. **Review Import**
   - Check location count
   - Verify geocoding
   - Review quality dashboard

### Set Up Public Campaign Page

1. **Create Campaign**
   - Configure targeting (federal/provincial)
   - Write email template
   - Set to published

2. **Share URL**
   - Copy public URL: `/campaigns/:id`
   - Share on social media
   - Embed in website

3. **Monitor Engagement**
   - View email statistics
   - Moderate responses
   - Check response wall

### Configure Newsletter Sync

1. **Enable Listmonk**
   - Set `LISTMONK_SYNC_ENABLED=true`
   - Configure API credentials
   - Restart services

2. **Initialize Sync**
   - Navigate to `/app/services/listmonk`
   - Click "Test Connection"
   - Click "Sync Participants"

3. **Manage Lists**
   - View list statistics
   - Configure sync settings
   - Monitor sync status

### Set Up Public Tunnel

1. **Create Pangolin Account**
   - Sign up at pangolin.bnkserve.org
   - Generate API key

2. **Configure Tunnel**
   - Navigate to `/app/services/pangolin`
   - Enter API key
   - Follow setup wizard
   - Deploy Newt container

3. **Test Public Access**
   - Visit public URL
   - Verify subdomain routing
   - Check SSL/TLS

### Create Landing Page

1. **Start New Page**
   - Navigate to `/app/pages`
   - Click "New Page"
   - Enter title and slug

2. **Design Page**
   - Click "Edit"
   - Use GrapesJS editor
   - Drag blocks
   - Customize content
   - Save (Ctrl+S)

3. **Publish**
   - Set to published
   - View at `/p/:slug`
   - Share URL

## Best Practices

### Campaign Management

- Use clear, action-oriented language
- Test email templates before launch
- Monitor response rates
- Moderate responses promptly
- Follow up with engaged supporters

### Field Organizing

- Clean location data before import
- Create manageable cut sizes (100-200 locations)
- Assign volunteers to familiar areas
- Print walk sheets in advance
- Review canvass progress daily

### Content Creation

- Write mobile-responsive pages
- Use SEO-friendly titles and descriptions
- Test pages on multiple devices
- Keep content concise
- Include clear calls-to-action

### System Administration

- Change default passwords immediately
- Enable monitoring stack
- Set up automated backups
- Review security audit findings
- Keep services updated

## Mobile Usage

### Volunteer Canvassing

Best on mobile devices:

- Full-screen map
- GPS tracking
- Touch-friendly controls
- Offline support (future)

### Admin Tasks

Best on desktop:

- Content editing (GrapesJS, email templates)
- Data import/export
- Configuration
- Monitoring dashboards

## Keyboard Shortcuts

### Page Editor

- **Ctrl+S** - Save page
- **Ctrl+Z** - Undo
- **Ctrl+Y** - Redo

### General

- **/** - Focus search (tables)
- **Esc** - Close modal/drawer

## Related Documentation

- [Admin Guide](admin-guide.md)
- [Campaign Manager Guide](campaign-manager-guide.md)
- [Map Organizer Guide](map-organizer-guide.md)
- [Volunteer Guide](volunteer-guide.md)
- [Content Editor Guide](content-editor-guide.md)
- [Features Overview](../features/index.md)
- [Troubleshooting](../troubleshooting/index.md)