# Influence Module

The Influence module provides a complete advocacy campaign platform for email campaigns, representative lookup, response walls, and engagement tracking. It enables supporters to contact their elected officials on issues that matter.

## Overview

The Influence module consists of five integrated components:

1. **[Campaigns](campaigns.md)** - Create and manage advocacy email campaigns
2. **[Representatives](representatives.md)** - Lookup representatives by postal code
3. **[Postal Codes](postal-codes.md)** - Postal code caching service
4. **[Email Queue](email-queue.md)** - Async email sending with BullMQ
5. **[Responses](responses.md)** - Public response wall with moderation

## Features

### Campaign Management

- Create campaigns with title, description, and email template
- Target federal, provincial, or municipal representatives
- Track campaign statistics (emails sent, responses)
- Public/private campaign visibility
- Featured campaign highlighting

### Representative Lookup

- Represent API integration (federal/provincial)
- Postal code → representative matching
- Representative information caching
- Multiple representative levels
- District boundary support

### Email Sending

- Async email queue with BullMQ
- Template processing with variable substitution
- SMTP delivery with retry logic
- Email tracking and statistics
- Test mode support (MailHog)

### Response Wall

- Public response submissions
- Email verification flow
- Moderation dashboard
- Upvoting system
- Response filtering and export

## User Flow

### Public User Experience

1. **Browse Campaigns** (`/campaigns`)
   - View featured campaigns
   - Search and filter (future)
   - Click campaign to learn more

2. **Campaign Detail** (`/campaigns/:id`)
   - Read campaign description
   - Enter postal code
   - View matched representatives
   - Customize email message
   - Send email

3. **Response Wall** (`/responses/:campaignId`)
   - Submit public response
   - Verify email address
   - View verified responses
   - Upvote responses

### Admin Experience

1. **Campaign Management** (`/app/influence/campaigns`)
   - Create campaigns
   - Edit templates
   - Configure targeting
   - View statistics
   - Manage visibility

2. **Response Moderation** (`/app/influence/responses`)
   - Review submissions
   - Verify/reject responses
   - Export data
   - Monitor engagement

3. **Representative Cache** (`/app/influence/representatives`)
   - View cached representatives
   - Refresh cache
   - Monitor lookup statistics

4. **Email Queue** (`/app/influence/email-queue`)
   - Monitor queue status
   - View failed jobs
   - Retry failed emails
   - Pause/resume queue

## Architecture

### Backend Components

**Modules:**
- `api/src/modules/influence/campaigns/` - Campaign CRUD + public routes
- `api/src/modules/influence/representatives/` - Represent API integration
- `api/src/modules/influence/postal-codes/` - Postal code cache service
- `api/src/modules/influence/responses/` - Response CRUD + verification
- `api/src/modules/influence/campaign-emails/` - Email tracking
- `api/src/modules/influence/email-queue/` - Queue admin routes

**Services:**
- `api/src/services/email.service.ts` - Nodemailer wrapper
- `api/src/services/email-queue.service.ts` - BullMQ queue + worker

**Database Models:**
- `Campaign` - Campaign definitions
- `CampaignEmail` - Sent email tracking
- `Response` - Public response submissions
- `PostalCodeCache` - Cached representative data

### Frontend Components

**Admin Pages:**
- `admin/src/pages/CampaignsPage.tsx` - Campaign management
- `admin/src/pages/ResponsesPage.tsx` - Response moderation
- `admin/src/pages/RepresentativesPage.tsx` - Cache admin
- `admin/src/pages/EmailQueuePage.tsx` - Queue monitoring

**Public Pages:**
- `admin/src/pages/public/CampaignsListPage.tsx` - Campaign listing
- `admin/src/pages/public/CampaignPage.tsx` - Campaign detail + email form
- `admin/src/pages/public/ResponseWallPage.tsx` - Response submissions

## Configuration

### Environment Variables

```bash
# Email
EMAIL_TEST_MODE=true          # Use MailHog instead of SMTP
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user@example.com
SMTP_PASS=password

# Represent API (optional)
REPRESENT_API_KEY=your_api_key

# Redis (required for BullMQ)
REDIS_PASSWORD=your_password
```

### Feature Flags

Email sending can be toggled via `EMAIL_TEST_MODE`:
- `true` - Emails sent to MailHog (localhost:8025)
- `false` - Emails sent via SMTP

## Integration Points

### Represent API

Represent API (https://represent.opennorth.ca/) provides:
- Federal MP lookup by postal code
- Provincial MLA/MPP lookup
- District boundaries
- Representative contact info

**Rate Limits:** 60 requests/minute

**Caching Strategy:**
- Cache postal code → representative mappings
- Refresh cache on 404 (postal code not found)
- Cache expiration: 30 days

### Listmonk Newsletter Sync

Campaign participants can be synced to Listmonk:
- Email submissions → subscribers
- Campaign → list assignment
- Opt-in sync via `LISTMONK_SYNC_ENABLED`

### Email Queue (BullMQ)

BullMQ provides:
- Async email processing
- Job retry with exponential backoff
- Queue monitoring and statistics
- Job persistence in Redis

## API Endpoints

### Public Endpoints

```
GET  /api/campaigns/public              # List public campaigns
GET  /api/campaigns/public/:id          # Get campaign details
POST /api/campaigns/:id/send-email      # Send campaign email
GET  /api/representatives/:postalCode   # Lookup representatives
POST /api/responses                     # Submit response
GET  /api/responses/verify/:token       # Verify email
GET  /api/responses/campaign/:id        # Get campaign responses
POST /api/responses/:id/upvote          # Upvote response
```

### Admin Endpoints

```
GET    /api/campaigns                   # List all campaigns
POST   /api/campaigns                   # Create campaign
GET    /api/campaigns/:id               # Get campaign
PATCH  /api/campaigns/:id               # Update campaign
DELETE /api/campaigns/:id               # Delete campaign
GET    /api/campaigns/:id/emails        # Get campaign emails
GET    /api/responses                   # List responses (admin)
PATCH  /api/responses/:id               # Update response
DELETE /api/responses/:id               # Delete response
GET    /api/representatives/cache       # View cache
POST   /api/representatives/cache/refresh # Refresh cache
GET    /api/email-queue/stats           # Queue statistics
POST   /api/email-queue/pause           # Pause queue
POST   /api/email-queue/resume          # Resume queue
```

## Related Documentation

- [Campaigns](campaigns.md)
- [Representatives](representatives.md)
- [Email Queue](email-queue.md)
- [Responses](responses.md)
- [Backend Campaign Module](../../backend/modules/campaigns.md)
- [Backend Representatives Module](../../backend/modules/representatives.md)
- [Backend Responses Module](../../backend/modules/responses.md)
- [Email Service](../../backend/services/index.md)
- [Campaign Manager Guide](../../user-guides/campaign-manager-guide.md)