admin/changemaker.lite
1
0
Fork 0
Code Issues Packages Projects Releases 31 Wiki Activity
changemaker.lite/mkdocs/docs/v2/features/influence/index.md

7.0 KiB
Raw Blame History

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 - Create and manage advocacy email campaigns
  2. Representatives - Lookup representatives by postal code
  3. Postal Codes - Postal code caching service
  4. Email Queue - Async email sending with BullMQ
  5. Responses - 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

# 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