changemaker.lite/mkdocs/docs/v2/index.md

Changemaker Lite V2 Documentation

!!! success "V2 is Production Ready" Changemaker Lite V2 is a complete architectural rebuild now running in production. This documentation covers the modern TypeScript stack with dual API architecture, React admin interface, and comprehensive feature modules.

Overview

Changemaker Lite V2 is a self-hosted political campaign platform that consolidates advocacy email campaigns, geographic mapping, volunteer management, and administration into a single unified TypeScript stack.

Key Highlights

• Dual API Architecture: Express.js (main features) + Fastify (media library)
• Modern Stack: TypeScript, Prisma + Drizzle ORM, PostgreSQL 16, Redis
• React Admin: Vite + Ant Design + Zustand state management
• JWT Authentication: Secure role-based access control with refresh tokens
• Comprehensive Features: 14 backend modules, 42 frontend pages, 8 critical services
• Production Monitoring: Prometheus, Grafana, Alertmanager with 12 custom metrics
• Security Audited: 13 findings addressed (Feb 2026)

Architecture Diagram

graph TB
    User[User Browser]
    Nginx[Nginx Reverse Proxy]
    Admin[React Admin GUI<br/>port 3000]
    ExpressAPI[Express API<br/>port 4000<br/>Prisma ORM]
    FastifyAPI[Fastify Media API<br/>port 4100<br/>Drizzle ORM]
    Postgres[(PostgreSQL 16)]
    Redis[(Redis)]
    BullMQ[BullMQ Queues]
    Listmonk[Listmonk<br/>Newsletter]
    Prometheus[Prometheus<br/>Monitoring]

    User --> Nginx
    Nginx --> |app.cmlite.org| Admin
    Nginx --> |api.cmlite.org| ExpressAPI
    Nginx --> |media.cmlite.org| FastifyAPI

    Admin --> ExpressAPI
    Admin --> FastifyAPI

    ExpressAPI --> Postgres
    ExpressAPI --> Redis
    ExpressAPI --> BullMQ

    FastifyAPI --> Postgres
    FastifyAPI --> Redis

    BullMQ --> Redis
    ExpressAPI --> Listmonk
    ExpressAPI --> Prometheus
    FastifyAPI --> Prometheus

Feature Modules

Influence Module

Email advocacy campaigns targeting elected representatives with:

• Campaign management with rich text editor
• Canadian representative lookup (postal code → MP/MPP/councillor)
• Public campaign pages with email submission
• Response wall with upvoting and moderation
• BullMQ async email queue with SMTP delivery
• Email verification and tracking

Learn more →

Map Module

Geographic mapping and volunteer canvassing with:

• Location CRUD with multi-provider geocoding (6 providers)
• Cut (polygon) management with spatial queries
• Volunteer shift scheduling and signup system
• Full canvassing system with GPS tracking and visit recording
• Walk sheets and QR codes for printable forms
• NAR 2025 data import (Canadian electoral data)

Learn more →

Landing Pages

GrapesJS-based page builder with:

• WYSIWYG editor with custom blocks
• Public rendering at /p/:slug
• MkDocs export for static documentation
• Mobile-responsive templates

Learn more →

Email Templates

Template management system with:

• GrapesJS email editor
• Variable substitution
• Integration with campaign emails
• Version control

Learn more →

Media Manager

Video library management with:

• Dual API architecture (Fastify microservice)
• Shared media public gallery
• Reaction system (6 standard emojis)
• Job queue monitoring
• Bulk operations

Learn more →

Newsletter Integration

Listmonk sync with:

• Participant/location/user syncing
• Subscriber list management
• Health monitoring
• API integration

Learn more →

Observability

Comprehensive monitoring with:

• Prometheus metrics (12 custom metrics)
• Grafana dashboards (3 pre-configured)
• Alertmanager notifications
• Service health checks
• Data quality dashboard

Learn more →

Quick Links

Getting Started

• Quick Start Guide - Get running in 5 minutes
• Installation - Detailed setup instructions
• Environment Setup - Configure your .env file
• First Login - Access the admin interface

Architecture

• Architecture Overview - System design and components
• Dual API Design - Express + Fastify architecture
• Database Schema - Prisma + Drizzle models
• Authentication Flow - JWT security model
• Frontend Architecture - React + Vite + Ant Design

Development

• Local Development - Set up your dev environment
• npm Commands - Common development tasks
• Database Migrations - Schema changes workflow
• Testing - Test strategy and execution
• Code Style - Standards and patterns

Deployment

• Docker Compose - Service orchestration
• Nginx Configuration - Reverse proxy setup
• Environment Variables - Complete reference
• Monitoring Stack - Prometheus + Grafana
• Backup & Restore - Data protection

API Reference

• Authentication API - Login, register, refresh
• Campaigns API - Campaign CRUD
• Locations API - Location management
• Media API - Video library
• Complete API Index - All endpoints

User Guides

• Admin Guide - Platform administration
• Volunteer Guide - Canvassing workflows
• Campaign Manager Guide - Running campaigns
• Map Organizer Guide - Location management
• Content Editor Guide - Landing pages

Technology Stack

Backend

• Express.js - Main API server (TypeScript, port 4000)
• Fastify - Media API microservice (TypeScript, port 4100)
• Prisma ORM - Database modeling and migrations (27+ models)
• Drizzle ORM - Media tables (lightweight schema-first)
• PostgreSQL 16 - Primary database
• Redis - Caching, sessions, rate limiting, BullMQ backend
• BullMQ - Job queues (email sending, geocoding)
• Winston - Structured logging

Frontend

• React 19 - UI library
• Vite - Build tool and dev server
• Ant Design 5 - Component library
• Zustand - State management
• React Router - Client-side routing
• Axios - HTTP client with interceptors
• Leaflet - Interactive maps
• GrapesJS - WYSIWYG page builder

Infrastructure

• Docker Compose - Service orchestration (20+ containers)
• Nginx - Reverse proxy with subdomain routing
• Prometheus - Metrics collection
• Grafana - Metrics visualization
• Alertmanager - Alert routing
• Listmonk - Newsletter platform
• MailHog - Email testing (development)

Project Status

Completed Phases (1-14)

✅ Phase 1: Foundation - Database, auth, basic API ✅ Phase 2: Auth + User Management - JWT, RBAC, user CRUD ✅ Phase 3: Admin GUI Foundation - React admin, routing, layouts ✅ Phase 4: Influence (Campaigns) - Campaign CRUD, admin pages ✅ Phase 5: Representatives + Postal Codes - API integration, caching ✅ Phase 6: Email Sending - BullMQ queue, SMTP, tracking ✅ Phase 7: Response Wall + Public Campaign View - Public pages, moderation ✅ Phase 8: Map (Locations) - Geocoding, CSV import, map rendering ✅ Phase 9: Map (Shifts) - Shift management, public signup ✅ Phase 10: Walk Sheets & QR Codes - Printable forms, QR generation ✅ Phase 11: Newsletter Integration - Listmonk sync ✅ Phase 12: Landing Page Builder - GrapesJS editor, MkDocs export ✅ Phase 13: Volunteer Canvassing - GPS tracking, visit recording ✅ Phase 14: Monitoring + DevOps - Prometheus, Grafana, backup

Additional Features

✅ Security Audit - 13 findings addressed (Feb 2026) ✅ NAR 2025 Import - Canadian electoral data support ✅ Media Manager - Dual API video library ✅ Email Templates - Template management system ✅ Data Quality Dashboard - Geocoding metrics ✅ Observability Dashboard - Monitoring integration

Current Phase

🚧 Phase 15: Testing + Polish - Comprehensive testing, documentation

Migration from V1

If you're migrating from Changemaker Lite V1 (NocoDB-based architecture), see the Migration Guide for:

• Breaking changes (NocoDB → Prisma, sessions → JWT)
• Data migration strategy
• API endpoint mapping
• Feature parity comparison

Contributing

Changemaker Lite is open source. We welcome contributions! See the Contributing Guide for:

• Development setup
• Code standards
• Pull request process
• Roadmap (Phase 15+)

Support

• Documentation Issues: Report on GitHub
• Security Issues: See Security Policy
• General Questions: Check Troubleshooting and FAQ

---

Last Updated: February 2026 | Version: 2.0.0 | Status: Production Ready