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

21 KiB
Raw Blame History

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
  2. Create new discussion: Start a discussion
  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
  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{ .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{ .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

Feedback

Have feedback on the roadmap?

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