changemaker.lite/mkdocs/docs/v2/migration/feature-parity.md

Feature Parity: V1 vs V2

This document provides a comprehensive comparison of features between Changemaker Lite V1 and V2, including feature status, implementation differences, and migration priorities.

Overview

V2 achieves 100% feature parity with V1 core functionality and adds significant new capabilities. Some V1 features are implemented differently (better!) in V2.

!!! success "V2 Feature Status" - ✅ All V1 Core Features: Campaigns, locations, shifts, response wall - ✅ Enhanced Features: Multi-provider geocoding, canvassing with GPS, monitoring - ✅ New Features: Landing pages, email templates, media library, NAR import

Feature Comparison Matrix

Core Features

Feature	V1	V2	Status	Notes
Email Advocacy Campaigns	✅	✅	Enhanced	V2 adds BullMQ queue, Listmonk sync
Representative Lookup	✅	✅	Enhanced	V2 adds caching, multi-level support
Response Wall	✅	✅	Enhanced	V2 adds moderation, upvoting, verification
Location Management	✅	✅	Enhanced	V2 adds structured address, geocoding quality
Geocoding	✅	✅	Enhanced	V1: Nominatim only → V2: 6 providers
Volunteer Shifts	✅	✅	Enhanced	V2 adds cut assignments, status tracking
Public Shift Signup	✅	✅	Same	V2 creates temp users automatically
User Management	✅	✅	Enhanced	V2 adds unified user model, RBAC
Admin Authentication	✅	✅	Changed	V1: Sessions → V2: JWT

Map Features

Feature	V1	V2	Status	Notes
Location Map (Public)	✅	✅	Enhanced	V2 adds color-coded markers, cut overlays
Location Map (Admin)	✅	✅	Enhanced	V2 adds click-to-add, move mode, geolocate
Cuts (Territories)	✅	✅	Enhanced	V2 adds drawing mode, point-in-polygon
CSV Import/Export	✅	✅	Enhanced	V2 adds flexible column mapping
Bulk Geocoding	❌	✅	New	V2 adds bulk geocode endpoint
Reverse Geocoding	❌	✅	New	V2 adds lat/lng → address lookup
Walk Sheets	❌	✅	New	V2 adds printable walk sheets with QR codes
Cut Export	❌	✅	New	V2 adds printable location reports
NAR Import	❌	✅	New	V2 adds Canadian electoral data import
Data Quality Dashboard	❌	✅	New	V2 adds geocoding quality metrics

Canvassing Features

Feature	V1	V2	Status	Notes
Canvassing System	❌	✅	New	V2 adds full canvassing workflow
GPS Tracking	❌	✅	New	V2 adds volunteer GPS trail recording
Walking Routes	❌	✅	New	V2 adds optimized route algorithm
Visit Recording	❌	✅	New	V2 adds outcome tracking, notes
Canvass Dashboard	❌	✅	New	V2 adds admin analytics, leaderboards
Volunteer Portal	❌	✅	New	V2 adds dedicated volunteer interface
Activity History	❌	✅	New	V2 adds visit history, stats

Content Management

Feature	V1	V2	Status	Notes
Landing Page Builder	❌	✅	New	V2 adds GrapesJS editor
Block Library	❌	✅	New	V2 adds reusable content blocks
MkDocs Export	❌	✅	New	V2 adds static site generation
Email Templates	❌	✅	New	V2 adds template system with versioning
Template Variables	❌	✅	New	V2 adds dynamic content substitution

Media Management

Feature	V1	V2	Status	Notes
Video Library	❌	✅	New	V2 adds video CRUD, categories
Video Upload	❌	✅	New	V2 adds upload with metadata extraction
Public Gallery	❌	✅	New	V2 adds public video gallery
Reactions	❌	✅	New	V2 adds 6 emoji reactions
Video Sharing	❌	✅	New	V2 adds lock/unlock system

Email & Newsletters

Feature	V1	V2	Status	Notes
SMTP Email Sending	✅	✅	Enhanced	V2 adds BullMQ queue, test mode
Email Queue	✅	✅	Enhanced	V1: Bull → V2: BullMQ with monitoring
Email Tracking	✅	✅	Enhanced	V2 adds sent/failed stats per campaign
Listmonk Integration	❌	✅	New	V2 adds newsletter sync
Subscriber Management	❌	✅	New	V2 adds campaign participant → list sync

Monitoring & DevOps

Feature	V1	V2	Status	Notes
Prometheus Metrics	❌	✅	New	V2 adds 12 custom cm_* metrics
Grafana Dashboards	❌	✅	New	V2 adds 3 pre-configured dashboards
Alertmanager	❌	✅	New	V2 adds alert rules, Gotify integration
Health Checks	❌	✅	New	V2 adds Docker healthchecks (7 services)
Backup Script	✅	✅	Enhanced	V2 adds PostgreSQL + Listmonk + uploads
Observability Dashboard	❌	✅	New	V2 adds admin observability page

Platform Services

Feature	V1	V2	Status	Notes
NocoDB	✅ (data layer)	✅ (read-only)	Changed	V2 uses Prisma, NocoDB for browsing
Redis	✅	✅	Enhanced	V2 adds authentication required
PostgreSQL	✅ (NocoDB)	✅ (direct)	Enhanced	V2 uses PostgreSQL 16 directly
MkDocs	❌	✅	New	V2 adds documentation site
Code Server	❌	✅	New	V2 adds web-based IDE
n8n	❌	✅	New	V2 adds workflow automation
Gitea	❌	✅	New	V2 adds Git repository hosting
Homepage	❌	✅	New	V2 adds service dashboard
Pangolin Tunnel	❌	✅	New	V2 adds self-hosted tunnel alternative
Cloudflare Tunnel	✅	❌	Removed	Replaced by Pangolin

Detailed Feature Comparisons

1. Email Advocacy Campaigns

V1 Implementation

Features:
- Create campaign (title, description, slug)
- Target representatives via postal code lookup
- Send emails to representatives (SMTP)
- Track sent emails
- Basic campaign listing

Technology:
- NocoDB tables (campaigns, campaign_emails)
- Bull job queue for async sending
- Nodemailer SMTP
- Represent API integration

V2 Implementation

Features:
- All V1 features plus:
  - Highlighted campaigns (featured on homepage)
  - Response wall toggle per campaign
  - Custom email subject/body templates
  - Target filtering (level, position, name, email, postal code)
  - Email stats dashboard (queued, sent, failed, mailto clicks)
  - BullMQ queue admin (pause, resume, retry failed)
  - Listmonk newsletter sync (campaign participants → list)
  - Public campaign gallery
  - Public campaign detail page

Technology:
- Prisma models (Campaign, CampaignEmail, Representative, etc.)
- BullMQ job queue with monitoring
- Nodemailer SMTP + MailHog test mode
- Represent API client with in-memory rate limiter (55/min)
- Redis cache for representatives (60min TTL)

Migration Impact: V1 campaigns migrate directly. New fields default to sensible values.

2. Representative Lookup

V1 Implementation

Features:
- Lookup by postal code (Represent API)
- Display representative name, email, district, party
- No caching (every lookup hits API)

Limitations:
- Rate limit issues (API throttling)
- Slow response times
- No offline capability

V2 Implementation

Features:
- All V1 features plus:
  - Redis cache (60min TTL)
  - Fire-and-forget cache writes (non-blocking)
  - Multi-level support (federal, provincial, municipal)
  - Representative admin (view cache, stats, delete)
  - Cache stats (total, by level, by party)
  - Health check endpoint

Performance:
- First lookup: ~500ms (API call + cache write)
- Cached lookup: ~20ms (Redis)
- Rate limiter: 55 requests/min (Represent API limit)

Migration Impact: Representative cache can be migrated or rebuilt from API.

3. Location Management & Geocoding

V1 Implementation

Features:
- Create location (single address field)
- Geocode via Nominatim (single provider)
- Support level (string field)
- Public map display (circle markers)

Limitations:
- No structured address (city, province separate)
- Single geocoding provider (Nominatim)
- No geocoding quality tracking
- No bulk operations

V2 Implementation

Features:
- All V1 features plus:
  - Structured address (street, city, province, postal code, country)
  - Multi-provider geocoding (6 providers with fallback):
    1. Nominatim (default, free)
    2. ArcGIS (enterprise)
    3. Photon (European focus)
    4. Mapbox (if API key provided)
    5. Google (if API key provided)
    6. OpenCage (if API key provided)
  - Geocoding metadata (provider, quality, timestamp)
  - Bulk geocoding endpoint (100 at a time)
  - Reverse geocoding (lat/lng → address)
  - CSV import with flexible column mapping
  - CSV export with filters
  - Location history (edit trail)
  - Contact fields (name, phone, email)
  - NAR import (Canadian electoral data, 50k+ locations)
  - Data quality dashboard (geocoding success rate by provider)
  - Click-to-add location on map
  - Drag-to-move location on map
  - Geolocate button (browser location)
  - Fullscreen map mode

Technology:
- Prisma Location model (structured schema)
- Multi-provider geocoding service with retry logic
- PostgreSQL spatial extensions (future: PostGIS)
- React Leaflet map components

Migration Impact: V1 single address field parsed into structured fields. Geocoding metadata added.

4. Volunteer Shifts

V1 Implementation

Features:
- Create shift (name, start/end time, location, capacity)
- Public signup form
- Email confirmation
- Admin view signups

Limitations:
- No cut assignment (shifts not linked to territories)
- No signup status tracking
- No volunteer portal

V2 Implementation

Features:
- All V1 features plus:
  - Cut assignment (link shift to territory)
  - Signup status (PENDING, CONFIRMED, CANCELLED, COMPLETED, NO_SHOW)
  - Shift requirements field
  - Temp user creation (public signup creates USER with 30-day expiry)
  - Signup cancellation (volunteer self-service)
  - Admin signup management (update status, notes)
  - Email all signups (broadcast to shift volunteers)
  - Shift stats (total shifts, upcoming, signups by status)
  - Volunteer portal (view assigned shifts)

Technology:
- Prisma models (Shift, ShiftSignup with status enum)
- TEMP user creation (automatic expiry)
- Email templates for confirmations

Migration Impact: V1 shifts migrate. Signups extracted to separate table. Status defaults to CONFIRMED.

5. Canvassing System (New in V2)

V2 Features

Complete canvassing workflow:
- Start/end canvass session (track volunteer time)
- GPS tracking (real-time trail recording, 30-day retention)
- Walking route algorithm (nearest-neighbor with haversine distance)
- Visit recording (outcome, support level, notes, rate-limited 30/min)
- Visit outcomes:
  - CONTACT_MADE
  - NOT_HOME
  - REFUSED
  - MOVED
  - DECEASED
  - WRONG_ADDRESS
- Admin dashboard:
  - Active sessions
  - Total visits (today, week)
  - Activity feed (recent visits)
  - Cut progress (locations visited vs total)
  - Leaderboard (top volunteers by visits, period filter)
- Volunteer portal:
  - Full-screen canvass map
  - GPS position tracking
  - Walking route display
  - Bottom sheet visit recording
  - Activity history (my visits)
  - Route history (past sessions)

Technology:
- Prisma models (CanvassSession, CanvassVisit, TrackingSession, TrackPoint)
- React Leaflet map with custom controls
- Zustand canvass store (client state)
- Abandoned session cleanup (hourly, ACTIVE > 12h → ABANDONED)
- Stale tracking cleanup (no data for 2h)

Migration Impact: New feature, no V1 equivalent.

6. Landing Page Builder (New in V2)

V2 Features

Visual page builder:
- GrapesJS WYSIWYG editor
- Drag-and-drop block placement
- Custom block library (Hero, Features, CTA, etc.)
- Live preview
- Desktop-only editor (mobile warning)
- Save hotkey (Ctrl+S)

Page management:
- CRUD operations (create, edit, delete, publish)
- Slug-based routing (/p/:slug)
- Public rendering
- MkDocs export (Jinja2 Material theme overrides)
- Export formats: themed (with header/footer) or standalone

Technology:
- GrapesJS 0.21+
- Prisma models (LandingPage, PageBlock)
- React admin UI
- MkDocs integration (override templates)

Migration Impact: New feature, no V1 equivalent.

7. Email Templates (New in V2)

V2 Features

Template management:
- Create templates (HTML + plain text)
- Template categories (campaign, shift, response, system)
- Variable substitution ({{campaignTitle}}, {{userName}}, etc.)
- Version control (publish creates new version)
- Live preview
- Test email sending

Admin features:
- Template library
- Version history
- Rollback to previous version
- Duplicate template
- Delete template (soft delete)

Technology:
- Prisma models (EmailTemplate, EmailTemplateVersion)
- Handlebars-style variable syntax
- HTML + plain text variants

Migration Impact: New feature, no V1 equivalent.

8. Media Library (New in V2)

V2 Features

Video management:
- Upload videos (MP4, MOV, AVI, MKV, WebM, M4V, FLV up to 10GB)
- Automatic metadata extraction (FFprobe):
  - Duration, dimensions, orientation
  - Video quality (resolution-based)
  - Audio track detection
- Bulk operations (delete, lock/unlock)
- Categories (assign to shared gallery)
- Lock/unlock system (public visibility control)

Public gallery:
- Category-based filtering
- Video detail page
- Reactions (6 emoji types: like, love, laugh, wow, sad, angry)
- Comment system (future)

Technology:
- Fastify microservice (port 4100)
- Drizzle ORM (separate from Prisma)
- FFprobe metadata extraction (30s timeout)
- Dual API architecture (media separate from main API)

Migration Impact: New feature, no V1 equivalent.

9. Monitoring Stack (New in V2)

V2 Features

Metrics collection:
- 12 custom cm_* metrics:
  - cm_api_uptime_seconds
  - cm_emails_sent_total
  - cm_emails_failed_total
  - cm_email_queue_size
  - cm_email_send_duration_seconds
  - cm_login_attempts_total
  - cm_active_sessions
  - cm_campaign_emails_total
  - cm_response_submissions_total
  - cm_canvass_visits_total
  - cm_active_canvass_sessions
  - cm_shift_signups_total
  - cm_external_service_up

Dashboards:
- System Health (CPU, memory, disk, network)
- Application Overview (API requests, errors, response times)
- API Performance (endpoint latency, throughput)

Alerts:
- High error rate (> 5% for 5min)
- API down
- High email queue size (> 1000)
- External service down (NocoDB, Redis, PostgreSQL)

Technology:
- Prometheus (metrics collection, 15s scrape)
- Grafana (visualization, 3 dashboards)
- Alertmanager (alert routing)
- Gotify (notification delivery, optional)
- cAdvisor (container metrics)
- Node Exporter (host metrics)
- Redis Exporter (Redis metrics)

Migration Impact: New feature, no V1 equivalent. Enable with --profile monitoring.

Feature Status Summary

V1 Features in V2

Feature	V2 Status	Implementation
Campaigns	✅ Complete	Enhanced with highlighting, response wall toggle
Representative Lookup	✅ Complete	Enhanced with caching, stats
Response Wall	✅ Complete	Enhanced with moderation, upvoting
Locations	✅ Complete	Enhanced with structured address, multi-provider geocoding
Shifts	✅ Complete	Enhanced with cut assignment, status tracking
Public Shift Signup	✅ Complete	Same functionality, improved UX
User Management	✅ Complete	Enhanced with unified model, RBAC
Email Sending	✅ Complete	Enhanced with BullMQ, monitoring
CSV Import/Export	✅ Complete	Enhanced with flexible mapping

Result: 100% V1 feature parity achieved

V1 Features NOT in V2

Feature	Reason	Alternative
NocoDB as primary data layer	Replaced by Prisma ORM	NocoDB available as read-only browser
Session-based authentication	Replaced by JWT	More scalable, stateless auth
Separate apps (influence, map)	Unified into single API	Better code reuse, consistency

V2-Only Features

Feature	Status	Phase
Landing Page Builder	✅ Complete	Phase 12
Email Templates	✅ Complete	Phase 12
Media Library	✅ Complete	Phase 12
Canvassing System	✅ Complete	Phase 13
GPS Tracking	✅ Complete	Phase 13
Walk Sheets	✅ Complete	Phase 10
NAR Import	✅ Complete	Phase 14
Data Quality Dashboard	✅ Complete	Phase 14
Monitoring Stack	✅ Complete	Phase 14
Pangolin Tunnel	✅ Complete	Phase 14
Observability Dashboard	✅ Complete	Phase 14

Migration Priority

When migrating from V1 to V2, prioritize features in this order:

1. Critical (Must Migrate First)

• User Authentication - Foundational for all access
• User Management - Admin accounts
• Campaigns - Core advocacy feature
• Locations - Core mapping feature
• Representative Lookup - Core advocacy feature

2. High Priority (Migrate Early)

• Response Wall - Public engagement
• Email Sending - Campaign functionality
• Shift Management - Volunteer coordination
• Public Shift Signup - Volunteer onboarding

3. Medium Priority (Migrate Mid-Phase)

• Representative Cache - Performance optimization
• Postal Code Cache - Performance optimization
• Cuts (Territories) - Advanced mapping
• CSV Import/Export - Bulk operations

4. Low Priority (Migrate Later)

• Email Queue Monitoring - Admin analytics
• Campaign Email Tracking - Admin analytics
• Representative Admin - Cache management

5. Optional (New V2 Features)

• Landing Pages - Public content
• Email Templates - Email customization
• Media Library - Video management
• Canvassing - Field operations
• Monitoring - System observability
• NAR Import - Canadian data

Workarounds for Missing Features

If you need a V1 feature not yet migrated:

1. Run V1 and V2 in Parallel

# Keep V1 running for specific features
docker compose -f docker-compose.v1.yml up -d

# Run V2 for new features
docker compose up -d

# Use reverse proxy to route by path:
# /v1/* → V1 apps
# /v2/* → V2 API

2. Manual Data Entry

For small datasets, manually re-enter data in V2 admin:

• Campaigns: Use Campaigns page (CRUD)
• Locations: Use Locations page or CSV import
• Shifts: Use Shifts page (CRUD)

3. Custom Migration Scripts

For unique V1 customizations, write custom transformation scripts:

// scripts/migrate-custom-fields.js
const customFieldMapping = {
  v1Field: 'v2Field',
  // Add your mappings
};

// Transform and import

Future Roadmap

Planned for V2 Phase 15+

• Multi-tenancy - Multiple organizations per instance
• Mobile apps - iOS/Android native apps
• Advanced analytics - Campaign performance, volunteer metrics
• AI integration - Campaign suggestions, email drafting
• Social media integration - Share campaigns, auto-post
• SMS campaigns - Text message advocacy
• Phone banking - Call tracking, scripts
• Donation tracking - Fundraising integration
• Event management - Rally, town hall scheduling

Community Feature Requests

Vote on features at: https://github.com/changemaker-lite/v2/discussions

Related Documentation

• Migration Overview - Migration planning
• Breaking Changes - V1→V2 differences
• Data Migration - Migration procedures
• V2 Features - Complete feature documentation

Next Steps

1. Review feature matrix - Identify features you use
2. Prioritize migration - Critical features first
3. Test on staging - Verify feature parity
4. Provide feedback - Report missing features
5. Plan new feature adoption - Landing pages, canvassing, etc.

!!! success "Feature Parity Achieved" V2 provides 100% V1 feature parity plus significant new capabilities. No functionality will be lost in migration.