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

```bash
# 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:

```javascript
// 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](index.md) - Migration planning
- [Breaking Changes](breaking-changes.md) - V1→V2 differences
- [Data Migration](data-migration.md) - Migration procedures
- [V2 Features](../features/index.md) - 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.