# Changemaker Lite V2 Roadmap

This roadmap outlines the development journey of Changemaker Lite V2, including completed phases, current work, and future plans.

## Overview

V2 is a complete rebuild of Changemaker Lite, transitioning from two separate Express apps to a unified modern TypeScript stack. The rebuild began in January 2025 and Phase 14 completed in February 2026.

**Current Status**: ✅ Phase 1-14 Complete | 🚧 Phase 15 In Progress

## Completed Phases (1-14)

### Phase 1: Foundation ✅ COMPLETE

**Timeline**: January 2025

**Deliverables**:
- Initialized `api/` with TypeScript, Express, Prisma
- Created comprehensive Prisma schema (30+ models)
- Set up environment configuration (Zod validation)
- Implemented middleware (error handling, validation, rate limiting)
- Built utility modules (logger, metrics)
- Initialized `admin/` with Vite + React + Ant Design
- Created Docker Compose orchestration
- Wrote `.env.example` with 100+ variables
- Backed up V1 to `docker-compose.v1.yml`

**Key Achievements**:
- Clean-room architecture established
- Type-safe foundation with TypeScript
- Scalable project structure

---

### Phase 2: Auth + User Management ✅ COMPLETE

**Timeline**: January 2025

**Deliverables**:
- Express Request type augmentation
- Zod auth schemas
- JWT auth service (login, register, refresh, logout)
- Auth middleware (JWT verification)
- RBAC middleware (role-based access)
- User CRUD service + routes
- Integration tested (Postman)

**Key Achievements**:
- JWT refresh token rotation (atomic transaction)
- 5 user roles (SUPER_ADMIN, INFLUENCE_ADMIN, MAP_ADMIN, USER, TEMP)
- Secure bcrypt password hashing
- User enumeration prevention (401 for invalid credentials)

---

### Phase 3: Admin GUI Foundation ✅ COMPLETE

**Timeline**: January 2025

**Deliverables**:
- Zustand auth store with token management
- Login page with form validation
- Protected route wrapper
- AppLayout with sidebar navigation
- UsersPage with CRUD operations
- Axios client with 401 refresh interceptor (callback pattern)

**Key Achievements**:
- Automatic token refresh (seamless UX)
- Role-based sidebar navigation
- Responsive Ant Design components

---

### Phase 4: Influence — Campaigns ✅ COMPLETE

**Timeline**: January 2025

**Deliverables**:
- Campaign Zod schemas
- Campaign service (CRUD, slug generation, toggle highlighting)
- Campaign admin routes
- CampaignsPage (table, filters, CRUD modals)
- Feature flag integration

**Key Achievements**:
- Unique slug generation
- Highlighted campaign toggle
- Response wall enable/disable per campaign

---

### Phase 5: Influence — Representatives + Postal Codes ✅ COMPLETE

**Timeline**: January 2025

**Deliverables**:
- Postal code validation schemas (Canadian format)
- Postal code cache service (Prisma)
- Represent API client (typed, rate-limited 55/min)
- Representative service (cache-first lookup, fire-and-forget writes)
- Representative admin routes (list, stats, detail, delete)
- RepresentativesPage (lookup, stats cards, table, detail modal)

**Key Achievements**:
- Redis cache (60min TTL, ~20ms lookup)
- In-memory rate limiter (Represent API limit)
- Cache stats dashboard (total, by level, by party)

---

### Phase 6: Influence — Email Sending ✅ COMPLETE

**Timeline**: January 2025

**Deliverables**:
- BullMQ email queue setup
- Email worker (SMTP via nodemailer)
- Campaign email service (compose, queue, track)
- Campaign email routes (send, track mailto, list, stats)
- Email queue admin routes (stats, pause, resume, clean)
- EmailQueuePage (monitoring, controls)
- CampaignEmailsDrawer (stats + list from CampaignsPage)

**Key Achievements**:
- Async email processing (BullMQ)
- Email test mode (MailHog)
- Rate limiting (30 req/hour per IP)
- Job retry with exponential backoff

---

### Phase 7: Influence — Response Wall + Public Campaign View ✅ COMPLETE

**Timeline**: January-February 2025

**Deliverables**:
- Response service (submit, moderate, verify)
- Response routes (3 routers: campaign-public, response-public, admin)
- Email verification (HTML templates, verify/report endpoints)
- ResponsesPage (filters, approve/reject/delete, detail drawer)
- ResponseWallPage (sort, filter, submit modal, upvote)
- Upvoting system (IP + user dedup, optimistic UI)
- CampaignPage (postal code lookup, email sending)
- CampaignsListPage (hero, featured, grid)
- PublicLayout (dark theme for public pages)

**Key Achievements**:
- Moderation workflow (PENDING → APPROVED/REJECTED)
- Upvote deduplication (IP address + user ID)
- Public campaign discovery

---

### Phase 8: Map — Locations ✅ COMPLETE

**Timeline**: February 2025

**Deliverables**:
- Multi-provider geocoding service (Nominatim, ArcGIS, Photon, Mapbox, Google, OpenCage)
- Location service (CRUD, geocoding, stats, bulk operations)
- Location routes (admin + public)
- MapSettings service + routes (singleton config)
- LocationsPage (table, stats, CRUD, geocode button, CSV import/export)
- MapSettingsPage (center/zoom, walk sheet config)
- Public MapPage (Leaflet, circle markers, color-coded, multi-unit grouping, cut overlays, geolocate, fullscreen)
- MapLegend component
- MapControls (click-to-add, move, geolocate, fullscreen)
- CutDrawingMode (polygon drawing with close detection)
- CutOverlays + CutOverlayControls

**Key Achievements**:
- 6 geocoding providers with automatic fallback
- Geocoding quality tracking (provider, timestamp, quality score)
- CSV import with flexible column mapping
- Admin map enhancements (click-to-add, drag-to-move)
- Point-in-polygon spatial queries (ray-casting algorithm)

---

### Phase 9: Map — Shifts ✅ COMPLETE

**Timeline**: February 2025

**Deliverables**:
- Shift service (CRUD, signup management)
- Shift routes (admin + public)
- ShiftsPage (CRUD, signups drawer, email all signups)
- Public ShiftsPage (calendar view, signup cards, signup modal)
- Temp user creation (30-day expiry)
- Confirmation emails

**Key Achievements**:
- Cut assignment (link shift to territory)
- Signup status tracking (PENDING, CONFIRMED, CANCELLED, COMPLETED, NO_SHOW)
- Public signup flow with temp user auto-creation
- Email all shift signups (broadcast feature)

---

### Phase 10: Walk Sheets & QR Codes ✅ COMPLETE

**Timeline**: February 2025

**Deliverables**:
- QR code generation endpoint (GET /api/qr, public, no auth)
- WalkSheetPage (printable form with QR codes, browser print)
- CutExportPage (printable location report with stats + table)
- Sidebar navigation + route wiring

**Key Achievements**:
- QR codes encode location data (address, coordinates, notes)
- Print-optimized CSS (page breaks, hide buttons)
- Cut-specific walk sheets (filter by cut)

---

### Phase 11: Listmonk Integration ✅ COMPLETE

**Timeline**: February 2025

**Deliverables**:
- Listmonk API client (typed HTTP, basic auth, native fetch)
- Sync service (campaign participants, locations, users → subscriber lists)
- Admin routes (status, stats, sync triggers, test connection, reinitialize)
- ListmonkPage (status dashboard, sync buttons, list stats)
- Opt-in sync flag (`LISTMONK_SYNC_ENABLED`)

**Key Achievements**:
- Newsletter integration (advocacy campaigns → subscriber lists)
- Automatic list creation/sync
- Proton Mail SMTP configuration (listmonk-init auto-configures)

---

### Phase 12: Landing Page Builder ✅ COMPLETE

**Timeline**: February 2025

**Deliverables**:
- Landing page service (CRUD, slug generation, MkDocs export)
- Page block service (seed blocks, CRUD, library API)
- GrapesJS editor integration (custom blocks, Ctrl+S save, error boundary)
- LandingPagesPage (table, search, settings modal)
- PageEditorPage (full-screen GrapesJS, desktop-only, forwardRef)
- Public LandingPage renderer (/p/:slug)
- MkDocs export (Jinja2 Material override template, themed + standalone modes)
- DocsPage (management, status cards, export table)

**Key Achievements**:
- Visual page builder (drag-and-drop)
- Custom block library (Hero, Features, CTA, Testimonials, etc.)
- MkDocs integration (static site generation)
- Jinja2 template export for Material theme

---

### Phase 13: Volunteer Canvassing System ✅ COMPLETE

**Timeline**: February 2025

**Deliverables**:
- Prisma models (CanvassSession, CanvassVisit, TrackingSession, TrackPoint)
- Canvass API (volunteer routes: start/end session, record visits, walking route)
- Canvass API (admin routes: dashboard stats, activity feed, cut progress, leaderboard)
- Walking route algorithm (nearest-neighbor with haversine distance)
- GPS tracking routes (volunteer + admin)
- Abandoned session cleanup (startup + hourly, ACTIVE > 12h → ABANDONED)
- Old tracking data cleanup (30-day retention, daily)
- Stale tracking session cleanup (no data for 2h, hourly)
- VolunteerLayout (top-nav, dark theme, mobile hamburger)
- VolunteerMapPage (full-screen Leaflet, GPS, markers, route, bottom sheet visit recording)
- VolunteerShiftsPage (assigned shifts, view only)
- MyActivityPage (visit history, outcome breakdown)
- MyRoutesPage (past session routes)
- CanvassDashboardPage (stats, activity feed, cut progress, leaderboard)
- ShiftsPage cutId dropdown (link shifts to cuts)
- Role-aware login redirect (ADMIN_ROLES → /app, USER/TEMP → /volunteer)

**Key Achievements**:
- Complete field canvassing workflow
- Real-time GPS tracking with trail visualization
- Optimized walking routes (nearest-neighbor algorithm)
- Visit outcome tracking (8 outcomes: CONTACT_MADE, NOT_HOME, REFUSED, etc.)
- Volunteer leaderboard (by visits, filterable by period)
- Rate limiting (30 visits/min per IP)

---

### Phase 14: Monitoring + DevOps ✅ COMPLETE

**Timeline**: February 2026

**Pangolin Tunnel**:
- Pangolin Integration API client (typescript)
- Admin pangolin routes (status, config, sites, resources, setup, sync, delete)
- PangolinPage (setup wizard + resource dashboard)
- Newt container in docker-compose.yml
- Env vars (PANGOLIN_API_URL, API_KEY, ORG_ID, SITE_ID, ENDPOINT, NEWT_ID, NEWT_SECRET)
- Retired Cloudflare scripts → `scripts/legacy/`

**Prometheus Metrics**:
- 12 domain-specific `cm_*` metrics (emails, auth, canvass, services, etc.)
- Instrumented modules (email-queue, auth, campaigns, responses, canvass, shifts, services)
- HTTP request metrics (duration, count, errors)

**Monitoring Configs**:
- Prometheus V2 API scrape job (removed V1 influence-app)
- Alert rules (rewritten for V2 metric names)
- Alertmanager Gotify webhook (commented, ready to enable)
- Grafana dashboards (3 dashboards: system-health, application-overview, api-performance)

**Docker Healthchecks**:
- 7 services with healthchecks (API, admin, nginx, NocoDB, n8n, Gitea, Listmonk)

**Backup**:
- `scripts/backup.sh` (V2 PostgreSQL + Listmonk + uploads archive)
- Manifest with timestamps, sizes, SHA256 checksums
- Configurable retention (default 30 days)
- Optional S3 upload (--s3 flag)

**Key Achievements**:
- Self-hosted tunnel alternative (Pangolin replaces Cloudflare)
- Comprehensive observability (Prometheus + Grafana)
- Production-ready monitoring stack
- Automated backup procedures

---

## Current Phase (15)

### Phase 15: Testing + Polish 🚧 IN PROGRESS

**Timeline**: February-March 2026

**Goals**:
- Comprehensive testing (unit, integration, E2E)
- Performance optimization
- Security hardening
- Documentation polish
- Bug fixes

**Planned Deliverables**:

**Testing**:
- [ ] API integration tests (Jest/Vitest)
  - Auth flow tests (login, refresh, logout)
  - Campaign CRUD tests
  - Location CRUD + geocoding tests
  - Canvass workflow tests
- [ ] Admin E2E tests (Playwright/Cypress)
  - Login flow
  - Campaign creation flow
  - Location management flow
  - Canvass session flow
- [ ] Test coverage reports (>80% target)
- [ ] Load testing (k6 or Artillery)
  - API endpoint stress tests
  - Database query performance
  - Email queue throughput

**Performance**:
- [ ] Database query optimization
  - Review Prisma queries for N+1 issues
  - Add missing indexes
  - Optimize spatial queries
- [ ] Frontend bundle size reduction
  - Code splitting
  - Lazy loading
  - Tree shaking optimization
- [ ] Redis cache tuning
  - Cache hit rate analysis
  - TTL optimization
  - Memory usage monitoring
- [ ] Image optimization
  - WebP conversion
  - Lazy loading
  - Responsive images

**Security**:
- [ ] Dependency audit (npm audit, Snyk)
- [ ] OWASP Top 10 review
- [ ] Security headers verification
- [ ] Rate limiting verification
- [ ] Input validation audit
- [ ] SQL injection prevention check
- [ ] XSS protection verification

**Documentation**:
- [ ] API reference completion (all endpoints documented)
- [ ] User guide polish (screenshots, videos)
- [ ] Developer docs review (architecture, database)
- [ ] Migration guide testing (V1→V2 procedure verification)
- [ ] Troubleshooting guide expansion (common issues)

**Bug Fixes**:
- [ ] Review and fix open GitHub issues
- [ ] Fix reported bugs (priority: critical > high > medium > low)
- [ ] Address edge cases
- [ ] Improve error messages

**Polish**:
- [ ] UI/UX refinements (spacing, alignment, colors)
- [ ] Accessibility improvements (keyboard nav, screen reader)
- [ ] Mobile responsiveness fixes
- [ ] Loading states improvements
- [ ] Error state improvements

**Progress**: 20% (security audit complete, NAR import complete, media upload complete)

---

## Future Roadmap (Phase 16+)

### Phase 16: Multi-Tenancy (Planned)

**Goal**: Support multiple organizations on single instance

**Features**:
- [ ] Tenant isolation (database row-level security)
- [ ] Subdomain routing (org1.cmlite.org, org2.cmlite.org)
- [ ] Tenant-specific settings
- [ ] Billing integration (optional)
- [ ] Admin cross-tenant management
- [ ] Tenant signup flow

**Technical Challenges**:
- Database schema changes (add tenantId to all tables)
- Prisma middleware for automatic tenant filtering
- JWT token tenant claim
- File upload isolation (per-tenant directories)

**Timeline**: 2-3 months (tentative Q2 2026)

---

### Phase 17: Mobile Apps (Planned)

**Goal**: Native iOS and Android apps for volunteers

**Features**:
- [ ] React Native app (iOS + Android)
- [ ] Volunteer canvassing optimized for mobile
- [ ] Offline mode (sync when online)
- [ ] Push notifications (shift reminders, campaign updates)
- [ ] Location services integration
- [ ] QR code scanning (walk sheets)
- [ ] Photo upload (location photos)

**Technical Stack**:
- React Native + Expo
- AsyncStorage for offline data
- React Query for sync
- Expo Notifications
- Expo Camera

**Timeline**: 3-4 months (tentative Q3 2026)

---

### Phase 18: Advanced Analytics (Planned)

**Goal**: Campaign performance and volunteer metrics

**Features**:
- [ ] Campaign analytics dashboard
  - Email open rates
  - Response submission trends
  - Geographic distribution
- [ ] Volunteer analytics
  - Canvassing efficiency metrics
  - Top volunteers leaderboard
  - Activity heatmaps
- [ ] Location analytics
  - Support level trends over time
  - Geocoding quality reports
  - Coverage maps
- [ ] Export to BI tools (Metabase, Superset)

**Technical Stack**:
- Prisma aggregations
- Chart.js or Recharts
- CSV/Excel export
- Optional: Metabase integration

**Timeline**: 2 months (tentative Q4 2026)

---

### Phase 19: AI Integration (Exploratory)

**Goal**: AI-powered features for campaign optimization

**Potential Features**:
- [ ] Campaign email drafting (GPT-4 integration)
- [ ] Response sentiment analysis
- [ ] Canvassing route optimization (ML algorithm)
- [ ] Volunteer assignment suggestions
- [ ] Predictive support level classification
- [ ] Automated data quality checks

**Technical Considerations**:
- OpenAI API integration (cost considerations)
- Privacy concerns (user data in AI models)
- Ethical AI usage guidelines
- Opt-in for AI features

**Timeline**: TBD (community feedback needed)

---

### Phase 20: Additional Integrations (Planned)

**Goal**: Connect to other campaign tools

**Potential Integrations**:
- [ ] **Social media**: Facebook, Twitter, Instagram posting
- [ ] **SMS campaigns**: Twilio integration for text banking
- [ ] **Phone banking**: VoIP integration for call tracking
- [ ] **Donation tracking**: ActBlue, Stripe integration
- [ ] **Event management**: Rally, town hall scheduling
- [ ] **Voter files**: VAN/Votebuilder import
- [ ] **Peer-to-peer texting**: Spoke, Relay integration

**Timeline**: Ongoing (community-driven priorities)

---

## Feature Requests

Have an idea for a new feature? We'd love to hear it!

### How to Request

1. **Search existing requests**: Check [Discussions](https://github.com/changemaker-lite/v2/discussions?discussions_q=category%3AIdeas)
2. **Create new discussion**: [Start a discussion](https://github.com/changemaker-lite/v2/discussions/new?category=ideas)
3. **Provide details**:
   - **Problem**: What problem does this solve?
   - **Use case**: Who would use this feature?
   - **Implementation ideas**: How might it work?
   - **Alternatives**: What workarounds exist today?

### Prioritization Process

Features are prioritized based on:

1. **Impact**: How many users benefit?
2. **Effort**: How complex to implement?
3. **Strategic fit**: Aligns with mission?
4. **Community votes**: Upvote discussions
5. **Funding**: Sponsored development

**High-priority features**:
- Requested by many users
- Low implementation effort
- Core to mission (campaign advocacy, volunteer management)

**Low-priority features**:
- Niche use cases
- High complexity
- Available via integrations

### Community Voting

Upvote feature requests in GitHub Discussions:

1. Go to [Ideas category](https://github.com/changemaker-lite/v2/discussions?discussions_q=category%3AIdeas)
2. Click 👍 on discussions you want
3. Comment with your use case

Most-upvoted features are considered for roadmap.

---

## Contribution Opportunities

Want to contribute to the roadmap?

### Code Contributions

- **Phase 15 (Testing)**: Write integration tests, E2E tests
- **Phase 15 (Performance)**: Optimize queries, reduce bundle size
- **Phase 15 (Documentation)**: Improve guides, add tutorials

[→ Find Issues](https://github.com/changemaker-lite/v2/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22){ .md-button }

### Design Contributions

- **UI/UX mockups**: Design future features
- **User research**: Interview campaign organizers
- **Accessibility audit**: Test with screen readers

### Documentation Contributions

- **User guides**: Write how-to guides
- **Video tutorials**: Create walkthrough videos
- **Translations**: Translate docs to other languages

### Sponsorship

Support development of specific features:

- **Individual sponsors**: $10/month (GitHub Sponsors)
- **Organization sponsors**: $500+/month (custom features, priority support)
- **One-time donations**: Sponsor specific features

[→ Sponsor on GitHub](https://github.com/sponsors/changemaker-lite){ .md-button .md-button--primary }

---

## Release Schedule

### Version Numbering

Changemaker Lite uses **Semantic Versioning**:

- **Major** (1.0.0): Breaking changes
- **Minor** (1.1.0): New features (backward compatible)
- **Patch** (1.1.1): Bug fixes

**Current version**: `2.0.0-beta.1` (Phase 15 in progress)

### Release Cycle

**Major releases**: 6-12 months (major new features, breaking changes)

**Minor releases**: 1-2 months (new features, no breaking changes)

**Patch releases**: 1-2 weeks (bug fixes, security patches)

### Upcoming Releases

**v2.0.0** (stable release):
- Target: March 2026
- Requires: Phase 15 complete (testing, polish)
- Breaking changes from beta: TBD

**v2.1.0**:
- Target: May 2026
- Features: TBD based on community feedback

**v2.2.0**:
- Target: July 2026
- Features: Possibly multi-tenancy (Phase 16)

---

## Long-Term Vision

**Mission**: Provide free, self-hosted tools for grassroots political campaigns.

**5-Year Vision** (2026-2031):

1. **Year 1** (2026): V2 stable, 100+ organizations using Changemaker Lite
2. **Year 2** (2027): Multi-tenancy, mobile apps, 500+ organizations
3. **Year 3** (2028): Advanced analytics, AI features, 1000+ organizations
4. **Year 4** (2029): Ecosystem of integrations, international campaigns
5. **Year 5** (2030): Changemaker Lite as standard platform for grassroots advocacy

**Success Metrics**:
- Number of organizations using platform
- Number of campaigns run
- Number of volunteers coordinated
- Number of emails sent to representatives
- Community contributions (PRs, issues, discussions)

---

## Breaking Changes Policy

### Commitment

We strive to minimize breaking changes in V2 minor releases. When breaking changes are necessary:

1. **Advance notice**: Announced 2 releases prior (e.g., deprecation in v2.1.0, removal in v2.3.0)
2. **Migration guide**: Detailed upgrade guide provided
3. **Deprecation warnings**: Console warnings in code
4. **Major version bumps**: Breaking changes only in major releases (v2→v3)

### Deprecation Process

1. **Deprecate**: Mark feature as deprecated (console warnings)
2. **Announce**: Publish deprecation notice in release notes
3. **Wait**: Keep deprecated feature for 2 releases minimum
4. **Remove**: Remove in next major version

**Example**:
- v2.1.0: Deprecate `/api/old-endpoint` (with warnings)
- v2.2.0: Still supported, warnings continue
- v2.3.0: Still supported, migration guide published
- v3.0.0: Removed (breaking change)

---

## Related Documentation

- [Contributing Guide](index.md) - How to contribute
- [Development Setup](development-setup.md) - Environment setup
- [Pull Request Guidelines](pull-requests.md) - PR process
- [V2 Plan](../../V2_PLAN.md) - Original roadmap document

## Feedback

Have feedback on the roadmap?

- **Discuss features**: [GitHub Discussions](https://github.com/changemaker-lite/v2/discussions)
- **Report priorities**: Email roadmap@cmlite.org
- **Vote on features**: Upvote discussions

Together, we're building the future of grassroots political campaigns! 🚀