234 lines
7.0 KiB
Markdown
234 lines
7.0 KiB
Markdown
# 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)
|